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.