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.

1. Modern REST API design principles and
rules
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
What is an API?

2. 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.

3. 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.
• 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.

4. • DELETE — deletes the specified resource.
• PATCH — applies partial modifications to a resource.
When to use REST?
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:
• 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.
• 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

5. 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.
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

6. 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.)
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)
There are also some good manners in naming endpoints as well:
• 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

7. obvious — /ids are understandable and preferable to /identification
numbers).
• 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.
What are the challenges in REST API?
• 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.

8. • 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.
References
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