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
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.
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.