Designing REST APIs 📝
Published: 2023-06-26 10:48:22

# 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](https://developer.mozilla.org/en-US/docs/Web/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](https://www.restapitutorial.com/httpstatuscodes.html) 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!**

# Sources! 🌐:
[Four Principles for Designing Effective APIs](https://www.ibm.com/topics/rest-apis#:~:text=the%20next%20step-,What%20is%20a%20REST%20API%3F,representational%20state%20transfer%20architectural%20style.)
[What is an API?](https://www.redhat.com/en/topics/api/what-are-application-programming-interfaces)
[Express Rate Limit](https://www.npmjs.com/package/express-rate-limit)
[REST API Security Essentials](https://restfulapi.net/security-essentials/)
[API security: 12 essential best practices](https://blog.axway.com/learning-center/digital-security/keys-oauth/api-security-best-practices)