API stands for "Application Programming Interface," and as a term, specifies how software should interact.
Generally speaking, when we refer to APIs today, we are referring more specifically to web APIs, those delivered over HyperText Transfer Protocol (HTTP). For this specific case, then, an API specifies how a consumer can consume the service the API exposes: what URIs are available, what HTTP methods may be used with each URI, what query string parameters it accepts, what data may be sent in the request body, and what the consumer can expect as a response.
Types of APIs
Web APIs can be broken into two general categories:
Remote Procedure Call (RPC) is a protocol that one program can use to request a service from a program located in another computer in a network without having to understand network details. (A procedure call is also sometimes known as a function call or a subroutine call.) RPC uses the client/server model. The requesting program is a client and the service-providing program is the server. Like a regular or local procedure call, an RPC is a synchronous operation requiring the requesting program to be suspended until the results of the remote procedure are returned. However, the use of lightweight processes or threads that share the same address space allows multiple RPCs to be performed concurrently. RPC is generally characterized as a single URI on which many operations may be called, usually solely via POST. Exemplars include XML-RPC and SOAP. Usually, you will pass a structured request that includes the operation name to invoke and any arguments you wish to pass to the operation; the response will be in a structured format.
Representational State Transfer (REST) is not a specification, but an architecture designed around the HTTP specification. The Wikipedia article on REST provides an excellent overview of the concepts, and copious resources.
REST leverages HTTP's strengths, and builds on:
Essentially, a good REST API:
You may recollect from earlier that Prime engine creates four class stubs for us, one each for the entity, collection, resource, and a factory for initializing the resource.
Within the ApiHawk engine documentation and, in particular, this chapter, uses the following terminology:
REST services return entities and collections, and provide hypermedia links between related entities and collections. Resource objects coordinate operations, and return entities and collections.