API Introduction

Introduction

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)
• Representational State Transfer (REST)

RPC

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.

REST

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:

• URIs as unique identifiers for resources.
• Rich set of HTTP verbs for operations on resources.
• The ability for clients to specify representation formats they can render, and for the server to honor those (or indicate if it cannot).
• Linking between resources to indicate relationships. (E.g., hypermedia links, such as those found in plain old HTML documents!)

Essentially, a good REST API:

• Uses unique URIs for services and the items exposed by those services.
• Uses the full spectrum of HTTP verbs to perform operations on those resources, and the full spectrum of HTTP to allow varying representations of content, enabling HTTP-level caching, etc.
• Provides relational links for resources, to tell the consumer what can be done next.

Defining the resource

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.

Terminology

Within the ApiHawk engine documentation and, in particular, this chapter, uses the following terminology:

• Entity - An addressable item being returned. Entities are distinguished by a unique identifier present in the URI.
• Collection - An addressable set of entities. Typically, all entities contained in the collection are of the same type, and share the same base URI as the collection.
• Resource - An object that receives the incoming request data, determines whether a collection or entity was identified in the URI, and determines what operation to perform.
• Relational Links - A URI to a resource that has the described relation. Relational links allow you to describe relations between different entities and collections, as well as directly link to them so that the web service client can perform operations on those relations. These are also sometimes called hypermedia links.

REST services return entities and collections, and provide hypermedia links between related entities and collections. Resource objects coordinate operations, and return entities and collections.