Resource API
How can a client manipulate data managed by a remote system, avoid direct coupling to remote procedures, and minimize the need for domain-specific APIs?
Many web services use messages to form their own domain-specific APIs.
These messages incorporate common logical commands like Create, Read (i.e. Get),
Update, or Delete (CRUD). This approach, however, can lead to a proliferation
of messages, even in relatively small problem domains. Consider, for example,
a set of services that manages company and contact information. In this scenario,
the client developer would have to use eight or more distinct messages, one for
each combination of a domain entity (i.e. company or contact) and CRUD
operation. An API like this might include messages like "CreateCompany",
"GetCompany", and so forth. The service owner would also have to create
response messages for the various service outcomes (e.g. "CreateCompanyResponse",
"GetCompanyResponse" etc.). Rather than creating a domain-specific API
comprised of messages like these, one could leverage the standards defined
in the HTTP specification.
Assign all procedures, instances of domain data, and files a Uniform Resource Identifier (URI).
Leverage HTTP as a complete application protocol to define standard service behaviors.
Exchange information by taking advantage of standardized media types and status codes when possible.
Resource APIs, as then name implies, provide access to Resources.
A resource may be a text file, media file (e.g. images, videos, audio),
a specific row in a database table, a collection of related data (e.g.
products), a logical transaction, a queue, a downloadable program, a business process (i.e.
procedure), almost anything. Clients invoke services by sending requests
to distinct URIs
designated for each resource.
Resource APIs use HTTP as a complete application protocol which
prescribes standard service behaviors. A client must therefore issue a
GET to retrieve data, PUT to create or update a resource, and so forth.
Each request and response may carry a standardized or proprietary
media type.
The requested URI and HTTP server methods issued by the client along
with the submitted or requested media type are used by the server to determine the
client's intent and service to be invoked. Once the service has been
invoked, it may process the client's request and return a response
containing the requested media type or a standard status code.