Here are 3 articles that cover different aspects of RESTful,
- RESTful Vs REST API Or Where Did REST Come From?
- Data-Centric RESTful API Vs Business Domain Centric API
- [Current] RESTful API additional standards and protocols
While building RESTful API you will definitely find cases that is not described by this approach, for example,
- queries, filters, pagination, and cursors
- hierarchy of resources within a single request
- links to other entities
- long-running operations with async handling
- bulk and batch requests
- error handling
- webhooks and push notifications
Such undocumented things made a ground for more specific protocols to handle particular problems. Most commonly used are OData (Open Data Protocol) and JSON:API.
OData (Open Data Protocol) defines the best practice for building and consuming RESTful APIs and helps you focus on your domain while building RESTful APIs without thinking about the approaches to define request and response headers, URL conventions, media types, status codes, HTTP methods, payload structure, and queries options, etc. OData provides a facility for an extension to fulfill any custom needs of your RESTful APIs and OData also guides you about tracking changes, defining functions/actions for reusable procedures and sending asynchronous/batch requests, etc.
OData is an ISO/IEC approved, OASIS standard which makes RESTful APIs easy to consume. The OData metadata is a machine-readable description of the data model of the API, it enables the creation of generic client proxies and tools. Some of them can help you interact with OData even without knowing anything about the protocol. Play with OData, XOData is the best start for the non-developers.
JSON:API is a RESTful API specification in JSON which covers how a client should request or modify resources, and how a server should respond to those requests. It helps to minimize both the number of requests and the amount of data transmitted between clients and servers. This also helps to achieve efficiency without compromising readability, flexibility, or discoverability.
To work with JSON API specification you need to use the JSON:API media type (application/vnd.api+json) for exchanging data.
Both OData and JSON:API specifications use a maximum of HTTP and define additional to RESTful standards, f.e.:
- filtering, query, pagination
- links to related resources
- updating, deleting resources
- the semantics of HTTP codes and methods
- partial request/response
- expand/Include in response
- paging and cursors
- response and error format
JSON data by itself is a flexible structure that does not have validation or intelligence, to enable such features JSON Schema was invented. JSON Schema is a powerful tool for validating the structure of JSON data. Basically, JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
JSON Schema introduces such features:
- describes your existing data format(s)
- provides clear human- and machine-readable documentation
- validates data that is useful for:
- automated testing
- ensuring the quality of client-submitted data.
The OpenAPI Specification came from the Swagger Specification donated by SmartBear Software, which is a specification for a machine-readable interface for describing, producing, consuming, and visualizing RESTful web services. It defines interface description for HTTP APIs, which is programming language-agnostic and allows both humans and computers to discover and understand the capabilities of a service without the source code, additional documentation, and network traffic inspection. With proper definition via OpenAPI consumers can understand and interact with the API with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling a service.
The OpenAPI Initiative (OAI) was created with a vision to standardize how APIs are described by a consortium of industry experts. As an independent structure within the Linux Foundation, OAI focuses on creating, developing, and promoting a description format that is vendor-neutral.
The Swagger is a commonly used extension for services to add descriptive and interactive documentation for web API. NSwag and Swashbuckle are commonly used NuGet packages to add Swagger UI which support OpenApi.