REST API: A Beginner’s Guide
I’m a software developer and technical writer focused on building and securing web applications. I work across the full stack (MERN) while developing a strong interest in application and API security.
My background in technical writing and API documentation shaped how I think about systems, clarity, structure, and correctness matter as much in code as they do in documentation. I’ve worked with tools like Postman, Swagger, and Figma, and I enjoy translating complex technical ideas into clear, usable knowledge.
These days, I’m learning and writing about web fundamentals, backend systems, and application security, documenting what I build, what I break, and what I’m learning along the way, with an eye toward secure, scalable software and future research.
Are you new to technical writing, web development, or software engineering? Do you want to learn about REST APIs, what they are, and how they work?
A REST API is an interface that enables two computer systems to exchange information over the internet securely. It follows a standard that directs the design and development of processes, facilitating interactions with data stored on a web server.
In this article, I will define what REST API is, the Benefits of using REST architecture, the Explanation of the REST acronym and its meaning, and what benefits you can get from applying them, etc.
This article is divided into two parts. The first part is an introduction to what a REST API is, and it covers the following topics: the Definition and Importance of a REST API; the Benefits of using a REST API; Architectural constraints and principles; and the Anatomy of a REST API.
Definition and importance of REST API
A REST API is an interface that enables two computer systems to exchange information over the internet securely. It follows a standard that directs the design and development of processes, facilitating interactions with data stored on a web server.
Typically, REST web APIs loosely base their operations on standard HTTP methods like GET, POST, PUT, and DELETE to access resources via URL-encoded parameters and exchange information securely over the internet using JSON or XML to transmit data. A REST API is an API that adheres to the architectural constraints of Representational State Transfer (REST). These constraints comprise a set of rules that enable the development of faster and more scalable APIs capable of supporting various data types.
Benefits of using REST architecture
1. Lightweight:
The HTTP standard, which the REST API relies on, is format-agnostic, allowing you to use XML, JSON, HTML, etc. This HTTP standard makes REST APIs fast and lightweight.
2. Scalability:
REST APIs are stateless, meaning the server does not need to store client information between requests. This statelessness allows REST to support concurrent requests without impacting performance since the server does not need to hold any client information and can process multiple requests simultaneously without the need to manage or synchronize client-specific data. This design allows for improved scalability and performance.
3. Independent of the platform:
REST APIs are versatile and can be used with almost any programming language, such as Python, C, etc., and on nearly every platform.
4. Testability:
REST APIs are easy to test because they are based on simple HTTP requests (GET, POST, etc.) using cURL or Postman, which allows you to quickly debug and test a REST API.
Understanding REST
The REST API protocol is widely used for building web services that enable interoperability between different software applications. As a developer and software engineer involved in constructing modern web applications that require seamless communication and integration with other software components or a technical writer who wants to document APIs, you should prioritize understanding the principles of the REST API.
By adhering to the principles of a REST API, you, as a developer, can create scalable, maintainable, and easily accessible web services for clients across various platforms and devices. In the following discussion, we will explore the fundamental principles of the REST API.
Architectural Constraints and Principles of REST
1. Statelessness
In REST APIs, the statelessness principle ensures that all the information needed to process a request is included within that request rather than making the server remember previous requests. The server does not store session-related data or maintain client-specific context between requests. As a result, both the client and the server remain unaware of each other's state. Holding the session state on the server violates the REST architecture's stateless requirement.
2. Uniform interface
In REST APIs, the uniform interface is a fundamental constraint that requires all requests targeting the same resource to adhere to a consistent format. This uniformity remains constant regardless of the source, device, or type of application, be it a mobile app, website, or any other client. By enforcing a standardized language for communication, this constraint enables clear differentiation between REST APIs and non-REST APIs while fostering interoperability among diverse systems.
3. Client-server separation
In REST APIs, the client-server separation constraint allows the client and server to operate independently. Here, all the client needs to worry about is requesting resources, while the server does not need to bother itself with the user state. The client-server separation helps improve interface flexibility across platforms and boost scalability.
4. Cacheable
Caching temporarily stores server responses on the client or intermediate caching servers. REST requires caching client-side or server-side resources, whether the response is cacheable, and how long responses can be cached on the client side. This cached mechanism allows the client to return the data from its cache for any subsequent request, and there would be no need to send the request again to the server. Caching increases page load speed and allows you to access previously viewed content without an Internet connection. As a result, the web application or mobile application makes fewer calls, reducing the server's load and latency. In turn, the application becomes more responsive and reliable.
5. Layered System
The REST API allows using the layered system architecture, which helps maintain separation between different responsibilities and allows for more straightforward modification or replacement of components within a layer without affecting the others. Each layer doesn't know anything about any layer other than that of the immediate layer, and there can be a lot of intermediate servers between the client and the end server.
6. Code on Demand
Code on demand is an optional feature. This feature allows the server to add more functionality to the REST client by sending executable code. The web developer can write the executable code in Python or C.
Anatomy of a REST API Request
The anatomy of a REST API request refers to the different parts or elements that make up an HTTP request.
A. Endpoint
An endpoint is the Uniform Resource Identifier (URI) you request, pointing to where and how to access and manipulate resources. To form the endpoint, you combine the base URL of the API with a path that identifies the specific resource or collection. E.g., Let's say we have a RESTful API for managing books. This is the base URL of the API https://omnitrix.com/api/, we want to access the endpoint for retrieving a specific book with an ID of 123.
We would combine the base URL(https://omnitrix.com/api/) with the path for the book resource (books/123). This would give us the endpoint URL: https://omnitrix.com/api/books/123.
We can retrieve information about the book with ID 123 from the API by accessing this endpoint.
In the above image, the endpoint is /weather.
B. HTTP methods (GET, POST, PUT, and DELETE)
The method is the type of request you send to the server. Below are the four essential HTTP methods in the REST API:
i. GET: The GET method gets a resource or a collection of resources from the server.
ii. POST: The POST method sends data to create a new resource on the server.
iii. PUT & PATCH: The PUT & PATCH method updates server resources. The PUT method sends data to update an ‘existing resource‘ on the server, while the PATCH method also sends data to update an ‘existing resource‘ on the server. However, PATCH only applies partial modifications to the resource instead of replacing the whole resource.
iv. DELETE: The DELETE method deletes a resource(s) from a server.
These are methods available from Postman for an API; as you can see, you can add a new method too.
C. Header
The header provides information relevant to both the client and server. It is essential to REST API calls as it allows for authentication data such as an API key, the name of the computer where the server is installed, etc., not included in the request body. HTTP Headers consist of property-value pairs that are separated by a colon. The example below illustrates a header that informs the server to anticipate JSON content.
E.g., "Content-Type: application/, JSON." missing the opening."
The image screenshot above shows a header for an API telling the server to return JSON content.
The request headers consist of metadata and additional information the client sends as part of an HTTP request. The headers include information about the request, such as the HTTP method used (e.g., GET, POST, or PUT), authentication credentials, and other relevant details. The server utilizes this information to understand and process the request correctly.
The server returns the response header to the client as part of the HTTP response. It includes crucial information like the status code (e.g., 200 OK, 404 Not Found), the content type of the response body, caching instructions, and other relevant metadata.
D. Body
In a REST API, the body refers to the data sent in the request or received in the response. The API sends the response body to the client, while the request body is used for sending and receiving data through the REST API.
Conclusion
And this concludes the first part of REST API: A Beginners Guide, where we covered the definition of REST API, amongst other things. You have learned that a REST API is an interface that enables two computer systems to exchange information over the internet securely. You have also learned about the benefits, the anatomy, etc.
With that said, I hope this article assists you in becoming a better web developer or technical writer in your tech journey.
Here is the link to the second part of the article, REST API A Beginner's Guide Part 2. I hope you find it insightful as we delve further into the intricacies of REST API development in the second part of this REST API beginner's guide.