Philosophy

Rules

Rule 1: Avoid writing global state

For example, the routing code is responsible for handling all input and output, so direct calls from methods to functions such as header() or echo should be avoided completely.

Rule 2: Endpoints must be embeddable

Endpoints should be able to call each other without worrying about global state. This follows from Rule 1, in that global state must be avoided for this, however this also means that endpoints can be expected to be called internally.

Rule 3: Explict is better than implicit

You should never have to guess where a variable came from, or why a method was called. Routes should have a 1:1 mapping with endpoints and magic catch-all routes should be avoided. Parameters should always be documented as if the API was a closed (source) box.

Rule 4: Reduce, reuse, recycle

Reduce the complexity of clients and the server.

Reuse code where possible.

Recycle endpoints by building on the existing instead of reinventing.

Guidelines

Guideline 1: Endpoints should operate like regular functions

By using the API, you’re essentially using a form of Remote Procedure Call. Both remote and local calls should look essentially the same while operating within the convention of REST calls for the remote calls.

Parameters to endpoints follow this rule, wherein remote parameters are matched up with defined parameters in the endpoint. More detailed structures are handled as entities, which have a clearly defined structure in the specification.

This follows from Rules 2 and 3.

Guideline 2: Endpoints should avoid assuming HTTP/JSON characteristics

Although the API usually operates over HTTP using JSON, endpoints can safely assume that the serialization may take place using a different serializer (such as protobufs or bson) over a different transport (such as ZeroMQ).

This doesn’t mean that endpoints need to reinvent the wheel; HTTP status codes and header names are used since this is the normal state. However, values should never be encoded in endpoints for HTTP transport rules or JSON encoding rules.

This follows from Rules 1 and 2.

Guideline 3: Base responses around entities

Being explicit with data formats means documenting everything. No one likes writing documentation constantly, so these data formats should be based around the concept of reusable entities.

This simplifies the code and reduces the workload of documentation.

This follows from Rules 3 and 4.