A big problem for REST APIs is its lack of standard specification. If you put 10 developers in a room and ask them what a REST API is, they are bound to all disagree on something. In order for developers at Hack4Impact to easily pick up, develop, or utilize APIs that are developed by Hack4Impact, we have made a REST API specification for all REST APIs developed inside of Hack4Impact.

What is REST?

Representational State Transfer (REST) is a specification on how to design APIs. This involves five required constraints. We do not follow all of these, as our APIs are generally only consumed by one client: our frontend, which is also written by us. The following list explains what aspects of each constraint we meet, and which ones we don't.

Uniform Interface

• We do guarantee that the API does not differentiate between two different clients issuing the same request.

• We do not promise to provide hypermedia in our responses. These would be providing next actions to the user based on the action they took.

• Client-Server Separation

  • We do guarantee that the client and server operate independently, and all the consequences of this.

• Stateless

  • We do guarantee that the server does not store client state and thus, each request must contain all the necessary information to complete the requested action

• Layered System

  • We do guarantee that the client is agnostic to how many layers there may between it and the server.

• Cacheable

  • We do not currently label responses as cacheable because the added complexity does not justify the advantages for our use cases.

Specification

This specification is not meant to be a stringent one. It's more a specific guideline in parts where standardization would provide more clarity and allow for greater developer velocity cross-team. Our Inspiration.

HTTP header functions

• GET -- Read a specific resource (by an identifier) or a collection of resources. Do not use a payload for this and it must not change any resource.
• POST -- Create a new resource. Also a catch-all function for operations that don't fit into the other functions. (e.g. complex query that does not scale well as a GET request)
• PUT -- Update a specific resource (by an identifier) or a collection of resources.
• DELETE -- Delete a specific resource by an identifier.

Sensible Resource Names

Creating good resource names will allow frontend developers and yourself easily navigate the API.

1. Use plural nouns, everything as lowercase, and use _ for spaces