The document outlines modern REST API design principles, emphasizing the importance of structure, naming conventions, and functionality. It discusses the significance of REST over SOAP, highlighting scenarios where REST is more suitable, such as statelessness, caching, and ease of coding. Additionally, key guidelines for creating effective APIs, including naming practices, error handling, and documentation, are presented.

1. MODERN
REST API
DESIGN
PRINCIPLES
AND RULES
Newsdata.io

2. Typically, when updating or developing an API like Newsdata.io which
is a news API for a service to provide news data with quick response
time, there are lengthy discussions about the API’s structure, naming,
and functions. Although, over time, certain rules have emerged that
can be applied to the process and aid in reaching a common ground
while developing.
Let’s get started with some basics

3. What is an API?
API is an abbreviation for Application Programming Interface. It is a
software interface that allows two applications to communicate with
one another without the need for user intervention.
APIs enable a product or service to communicate with other products
and services without requiring knowledge of how they are
implemented.
It facilitates communication between the provider and the client. It is a
type of software interface that provides a service to other programs.
An API specification is a document or standard that describes how to
build or use such a connection or interface.
An API is said to be implemented or exposed by a computer system
that meets this standard. API can refer to either the specification or
the implementation.

4. What is REST?
REST was created to work specifically with components such as
media components, files, or even objects on a specific hardware
device. A RestFul web service is any web service that adheres to the
REST principles. For working with the required components, a Restful
service would use the standard HTTP verbs GET, POST, PUT, and
DELETE. REST is an acronym that stands for Representational State
Transfer.

5. GET — requests a representation of the specified resource.
Requests using GET should only retrieve data.
POST — submits data to the specified resource.
PUT — replaces all current representations of the target resource
with the request data.
DELETE — deletes the specified resource.
PATCH — applies partial modifications to a resource.
When to use REST?
Limited resources and bandwidth — Because SOAP messages are
heavier in content and consume far more bandwidth, REST should
be used when network bandwidth is limited.
When designing web services, one of the most contentious issues is
whether REST or SOAP should be used. In the following situations,
REST services should be used:

6. Statelessness — If there is no need to keep information in a
consistent state from one request to the next, REST should be
used. If you need a proper information flow, where some
information from one request needs to flow into another, SOAP is
a better choice. We can use any online shopping site as an
example. Typically, these sites require the user to first add items
that must be purchased to a cart. To complete the purchase, all of
the cart items are transferred to the payment page. This is an
example of an application that would benefit from the state
feature. The cart items’ state must be transferred to the payment
page for further processing.
Caching — If a large number of requests must be cached, REST is
the ideal solution. Clients may request the same resource multiple
times at times. This may result in an increase in the number of
requests sent to the server. The most frequently used query
results can be saved in an intermediate location by implementing a
cache. As a result, whenever a client requests a resource, it will
first check the cache. If the resources are available, the process
will not proceed to the server. As a result, caching can aid in
reducing the number of trips to the web server.
Ease of coding — Coding REST Services and then implementing
them is far easier than SOAP. So, if you need a quick win solution
for web services, REST is the way to go.

7. REST is the most common API architecture in today’s world
(representational state transfer). When using REST, you must
adhere to JSON rules and format your requests in invalid JSON.
Aside from that, a good API should adhere to the following
guidelines:
APIs must be separated from the backend, data storage, client,
and so on. Because of security and flexibility, it must be a separate
layer.
State less — different requests should have no knowledge of one
another and be processed independently. That also means that
each request must include all of the information required for
processing.
API should function in the same way regardless of whether a
client sends a request (e.g. is it a web-server or load-balancer or
any other client).
REST APIs typically send static resources, but responses can also
contain executable code in rare cases (such as Java applets). In
these cases, the code should only be executed when needed.
Cacheability — Resources should be cacheable on the client or
server-side whenever possible. The goal is to improve client-side
performance while increasing server-side scalability. However,
there are special headers such as Cache-Control that can be used
to control the cache behavior.
Handle errors and return the appropriate error codes. Instead of
throwing an internal error to the user, handle it and send the
corresponding code and message (e.g. 404 — not found.)

8. Remember that API should be idempotent (that means that can be
invoked many times with the same result). Users can sometimes
send duplicate requests to the API. These duplicate requests may
have been made inadvertently (or intentionally due to timeout or
network issues). As a result, APIs must be fault-tolerant in order
for duplicate requests to yield the same results (only POST
request is not idempotent).
To create documentation for your API, use swagger or another
tool. Documentation is a critical component (if someone going to
use that API someday)
Endpoints should be named with nouns that specify the contents
of the resource rather than adding a verb for the function that is
being performed (e.g., name endpoint /users and use different
HTTP methods for working with the user’s entity rather than
creating several endpoints like /get-user, /add-user, etc.).
Use clear names: The name of the endpoint should be clear and
intuitive (do not use any shortcuts or abbreviations unless they are
obvious — /ids are understandable and preferable to /identification
numbers).
There are also some good manners in naming endpoints as well:

9. Forward slashes are used to create a hierarchy by grouping
endpoints into logical groups (/departments/ids and
/departments/managers are preferable to /departments-ids and
/departments-managers).
Use only lowercase letters: Because URIs are case-sensitive
(according to the specification), it is best to avoid using upper case
unless absolutely necessary.
Separate words with “-”: different words in the endpoint name are
usually separated by “-” rather than underscores or camel case.
Avoid special characters: URLs can only be sent and received
using the ASCII character set, so it is possible to use only
characters from that set (also there are some expectable but
unsafe characters like “ percent ”,”[]”,”{}”,”|”,” “,”<>” and it is better
to try to avoid using them as well).
The majority of REST APIs are built in conjunction with microservice
architecture. In that case, an API structure like this will allow you to
change the underlying logic, add or remove components, and so on
without changing the communication protocol with other services.

10. Lack of Security — Unlike SOAP, REST does not impose any type
of security. This is why REST is ideal for publicly accessible URLs,
but when it comes to passing confidential data between the client
and the server, REST is the worst mechanism to use for web
services.
Lack of state — Most web applications necessitate the use of a
stateful mechanism. For example, if you had a purchasing site with
a shopping cart mechanism, it is necessary to know the number of
items in the shopping cart before the actual purchase is made.
Unfortunately, the client bears the burden of maintaining this
state, which makes the client application heavier and more difficult
to maintain.
When to use REST?

11. Reference
1. https://levelup.gitconnected.com/good-api-design-bad-api-design-
2405dcdde24c
2. https://newsdata.io
3. https://rajat-testprepkart.medium.com/what-are-restful-web-services-
476dd2f99330
4. https://www.guru99.com/comparison-between-web-services.html