REST-ful API Practices #

In REST the primary unit of identification is a resource that is accessed by a URI. A RESTful URI must convey the resource’s model to its clients.

Resource Naming conventions #

• Use nouns instead of verbs. Nouns have properties and resources have attributes.
• Use plural nouns
• Multi-worded nouns

Considerations #

Different companies have used different strategies. There is no universal consensus on multi-worded nouns.

• Camel Case
• Underscores
• Hyphens

Projects in this repository follow hyphenated names. Since URLs are ideally case sensitive we avoid using it. So, between underscores and hyphens, we are going with hyphens as our choice of separators.

Nest Hierarchical objects #

Versioning #

By default, support the response with the most updated API version if none is requested. It is recommended that the clients explicitly request the required version trough the request headers.

Accept: application/vnd.github.v3+json

Backwards Compatibility #

API contract can change multiple times over the course of development. However, once a change is implemented in production breaking a contract is a grave offence. Nevertheless, contracts won’t be the same during the life of the application and changes are inevitable.  

Date and Time #

All date and time should be in ISO 8601 format.

ISO 8601

HTTP Verbs #

HTTP Headers #

API First Approach #

Documentation #

OpenAPI

Authentication #

Authentication tokens must be passed through Authorization headers. Do not use query parameters.

References #

• External-I
• Stack Overflow
• Github