5 Things I wanted to know about REST API when I was starting
Tags: restapi, java, programming
Published: 2024-05-05 16:07:33

### What is a REST API?

API (Application Programming Interface) is a set of routines, protocols, and tools for building software applications.

REST (Representational state transfer) is an architectural style for distributed hypermedia systems. It was introduced in 2000 by [Roy Fielding in his dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).

So, a REST API or a RESTFul API is an API that implements the REST principles.

### 1. RFC what is it?

RFC stands for "Request for Comments." An RFC is a document that describes various aspects of the design, specifications, and working of the internet and internet-related systems.

In the context of computer networking and the Internet, an RFC is a type of publication from the Internet Engineering Task Force (IETF) and the Internet Society (ISOC). The RFC documents contain technical specifications and organizational notes for the Internet.

To know more about RFC access: [https://www.ietf.org/standards/rfcs/](https://www.ietf.org/standards/rfcs/)

There are some RFCs that were created to deal with REST, the first one was RFC 2616 created in June 1999 and became obsolete by RFC7230 - RFC7235 created in June 2014, and now these RFCs are also obsolete because of the new RFC9110, RFC9111 and RFC9112 that were created in June 2022.

### 2. What are the most common HTTP Methods?



![HTTP Methods](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F54fc5fbd-77bc-4dd8-a4bf-fee397b3de3e_1023x363.png)

For more information, access [RFC9110 - HTTP Methods](https://datatracker.ietf.org/doc/html/rfc9110#section-9)

### 3. What is idempotent?

An operation is considered **idempotent** if performing it multiple times has the same effect as performing it once. In other words, no matter how many times you repeat the operation, the system's state remains consistent. This property is crucial for the reliability and predictability of RESTful services.

**Benefits of Idempotence:**

- **Predictable Behavior:** Developers can rely on the fact that repeating an idempotent operation won't cause unexpected side effects.
    
- **Retry Mechanisms:** Idempotence is useful for designing reliable systems. If a request fails, it can be safely retried without causing unintended changes.
    

### 4. What are the most common HTTP Statuses?

- 1xx (Informational): The request was received, continuing process
    
- 2xx (Successful): The request was successfully received, understood, and accepted
    
- 3xx (Redirection): Further action needs to be taken in order to complete the request
    
- 4xx (Client Error): The request contains bad syntax or cannot be fulfilled
    
- 5xx (Server Error): The server failed to fulfill an apparently valid request
    

**These are some common HTTP Status:**

![HTTP Status](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F832c9c07-f04d-478e-8084-91aecca190fc_1037x616.png)

It's crucial to know the most common HTTP status codes, as there are over 30 of them. Start by mastering the most common ones to gain a solid foundation in web development.

To know more about the HTTP status, access the [RFC9110 - Status Codes](https://datatracker.ietf.org/doc/html/rfc9110#section-15)

### 5. What is the Glory of REST?

Leonard Richardson breaks down the principal elements of a REST approach into three steps:

![Richardson Maturity Model](https://substackcdn.com/image/fetch/w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F5fe98451-9b9b-43b6-a2d7-b21bd971224f_673x398.png "Richardson Maturity Model")

- Level 0 (The Swap of POX): At this level there is only one endpoint, and normally it doesn't use HTTP Status, so the API will return 200 OK on all types of responses and the output will contain the error. At this level there is a single HTTP Method, usually POST.
    
- Level 1 (Resources): At this level it will be more than one endpoint, actually one endpoint per resource, but still not using the HTTP Verbs or HTTP Status.
    
- Level 2 (HTTP Verbs): At this level will use the HTTP Verbs and the HTTP Status
    
- Level 3 (Hypermedia Controls): This is the most mature level of Richardson’s model, in this level the API will use HATEOAS(Hypermedia as the Engine of Application State), which encourages easy discoverability.
    

If you want to know more about it, read these articles:

- [Richardson Maturity Model - Martin Fowler's blog](https://martinfowler.com/articles/richardsonMaturityModel.html)
    
- [What is Richardson Maturity Model](https://restfulapi.net/resource-naming/)
    

### Conclusion

To write a wonderful API, you must know RFC and best practices. This will help you create an API that follows the common standard, then it will be easy to be a customer of your API.

Another important thing is to define a REST API design. It will be easier to use your API if you have some well-known design. Try searching for famous APIs and see how they are designed to understand how to do this and what are the best practices.

Now you know what is an API and what is a REST API, but what I showed here is just the basics concepts, so keep studying 😊

### References:

- **REST API - Design Rulebook** **-** Mark Masse
    
- [AZURE API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
    
- [Best practices for REST API design - Stackoverflow Blog](https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/)
    
- [Swagger specification](https://swagger.io/specification/)
    
- [RESTFUL API](https://restfulapi.net/)
    
- [Stripe API Design](https://stripe.com/blog/payment-api-design)