Designing REST APIs 📝

What are REST APIs?

Let's break it down.
What is an API?
An API (Application Programming Interface) is a set of rules and protocals that allow different computer programs to communicate and interact with each other. An API acts as a messenger between the applications so they can do many things such as:

Accessing Remote Services
Data Integration
Functionality Extension
Customization
Platform Interconnectivity
Mobile App Development

Cool, but what is REST?
REST (Representational State Transfer) provides a consistant approach to designing and building an API. In REST, data can be identified by unique URLs. ( URIs, Uniform Resource Identifiers ) While REST isn't tied to HTTP, most REST APIs use HTTP as the application protocalls. So interactions occur though HTTP methods.

Best Practices for RESTFUL APIs ☝️🤓

There is a huge emphasis on a uniform interface in regards to REST.

Path Names

Some things to keep in mind when creating path names are:

Use nouns, try avoiding verbs. It should just represent the resoure instead of describing behavior. For example, /resources instead of /getresource
Pluralize, when a resource represents a collection. For example,/books instead of /book. If you want to represent a singluar book it would be /books/<int:id>
Represent Hierachy for Related Resources, the URI should reflect this. For example, users/{userID}/posts represents posts relating to a specific user.
Avoid Ambiguity but Keep it Short, ambigous path names could cause confusion, same goes for longer URI names.
Versioning, for when you need to show changes to the API by adding a version to the URI path. For example, /v1/books and /v2/books represents different versions.

Use JSON Format

Using JSON (JavaScript Object Notation) format for RESTful APIs offers compatiability with RESTful principles.

Easy to Understand Responses

Responses are crucial, some pointers for creating REST responses are:

Appropriate Status Codes, HTTP status codes can quickly tell us what just occured with the request we executed. It also quickly let's us know errors in our requests.
Clear Response Bodies, will contain relevant data to the request. It should be in a consistant format throughout.
Error Handling, you should be providing an informative error message in the response body with the appropriate HTTP status code.
Security, ensure that sensitive information is not displayed in the response body, implement data encryption to protect that data.

Rate Limiting

Controlling the rate of requests to a web API ensures fair usage and protects the server from overload.

Clear Rate Limiting Policies, clearly define the limits like the maximus number of requests allowed per minute per hour.
Tie Authentication, by requiring users to authenticate, you can monitor the number of requests and grant access to different endpoints.

Good Documentation

Comprehensive documentation is important for successful useage of an API. The docs should be also publicly accessible. Some things to consider adding to your API docs are:

Overview, introduction, explaining the API's purpose, how to use the API, and the problem it solves.
Getting Started Instructions, tells users how to obtain API key, provides any necessary sey up, and authentication methods.
Resources and Endpoints, lists all API resources and endpoints with a brief description. Includes their URLS, request methods, and expected response body.
Error Handling, possibile error reponses the API might return, then provide specific error handling instructions.
Rate Limiting and Catching Strategies
Tutorials, adding real world examples and then tutorials on how your API can solve specific issues helps users get a better idea on what your API is used for.
Keep it Up to Date!