REST API Guidelines

Details

• Created by: Divij Sharma
• Reviewed by: Gaurav Mishra, Shaheem Azmal M MD

Motive

Since this project primarily focuses on REST API development and improvement, it is crucial to establish a comprehensive guideline from the beginning. This guideline will serve as a set of rules to follow and provide a clear objective to achieve. After researching various reputable open-source projects and reviewing several design guides, I have prepared a detailed guideline document. Please refer to the table below for more information.

Guidelines

#	Guideline	Description	Example
1	Uniform Interface	The uniform interface principle in RESTful API design advocates for a consistent and standardised approach to interactions between clients and servers. Advantages- Predictability Standardisation Scalability	This is widely used in FOSSology, for instance, a user can send a POST request to /upload endpoint to post a new upload and can get that particular upload by making a GET request at /upload/{id}.
2	Platform Independent	Any client should be able to call the API, regardless of how the API is implemented internally. This requires consistent data sharing rules and formats. Advantages- Flexibility Integration	Consider a RESTful API for a weather service. Clients, such as web applications, mobile apps, and IoT devices, can retrieve weather data using standardised API endpoints, regardless of the programming languages or frameworks used to develop these clients.
3	Backward Compatible	The web API should be able to evolve and add functionality independently from client applications. As the API evolves, existing client applications should continue to function without modification. Advantages- Gradual updates Stability Strategic updates	Suppose a social media platform introduces a new endpoint for retrieving user profile information in a more efficient manner. To ensure backward compatibility, the platform retains support for the existing endpoint structure, allowing older client applications to continue accessing user profiles without any disruptions. FOSSology implements this by supporting V1 REST API endpoints in deprecated mode.
4	Stateless Behaviour	REST APIs use a stateless request model. The only place where information is stored is in the resources themselves, and each request should be an atomic operation. For this to hold, each request must contain all the information necessary to understand and process the request. Advantages- Caching Consistency	Consider a shopping website with a RESTful API for managing user sessions and shopping carts. Each client request, such as adding items to the cart or proceeding to checkout, includes all the necessary information (e.g., item IDs, quantities) for the server to process the request. The server does not store any client-specific data between requests, ensuring that the API remains stateless and scalable, regardless of the number of concurrent users.
5	Resource-Oriented Design	REST APIs are structured around resources, which represent any object, data, or service accessible by clients. Also, resources of the same type should be clubbed under the same endpoint. Each resource is uniquely identified by a URI (Uniform Resource Identifier), providing a consistent and predictable means of access where CRUD operations can be defined. Advantages- Easy maintenance Uniformity The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by RFC3986.	Suppose we have a RESTful API for managing user accounts in an e-commerce platform. Each user account is treated as a resource, with a unique URI (/users/{id}) representing the resource. Clients can perform CRUD operations on user accounts using standard HTTP methods enabling seamless interaction with the API endpoints. Also implemented in FOSSology
6	Entity-Centric URIs	Base resource URIs on nouns representing business entities (plural nouns for collections) rather than verbs indicating operations. Ensure each business entity has a distinct and simple URI, reflecting its unique identity and purpose within the system. Advantages- Semantic Consistency Clarity and intuitiveness	Suppose we have a RESTful API for managing products on an e-commerce platform. Each product is considered a business entity, and the URIs for accessing these products follow a noun-based pattern, such as /products/{product_id}. This approach ensures that each product has a unique and distinct URI, facilitating efficient resource identification and interaction within the API.
7	Hierarchical Organisation	Organise resources in a hierarchical manner to establish a structured and intuitive API architecture. Use parent-child relationships to represent nested resources, ensuring logical grouping and defined scope within the API. With each /, the scope of the resource should become more specific. Advantages- Logical Structuring Simplified Navigation	In a content management system (CMS) API, blog posts may be organised under a parent resource representing a user's blog. The hierarchical URI structure could be /user/{uid}/blog/{bid}, where each segment represents a nested relationship between resources. This organisation provides a clear and intuitive path for accessing blog posts within the context of a specific user and blog.
8	Decouple Web API from Data Sources	Think of the web API as an abstraction of the database. If necessary, introduce a mapping layer (DAO) between the database and the web API. That way, client applications are isolated from changes to the underlying database scheme. Advantages- Abstraction Security	In a web API for a retail platform, the API endpoints should interact with an abstraction layer or service interface that encapsulates data access logic. This abstraction shields the API from direct dependencies on database implementations, enabling the use of various storage solutions (e.g., SQL databases, NoSQL databases, cloud storage) without affecting the API's external behaviour.
9	Media types	Standardise the use of media types, also known as MIME types, to specify data formats exchanged between clients and servers in the HTTP protocol. For textual data, the widely supported JSON format (media type = application/json) is commonly used in web APIs. Advantages- Interoperability Clear communication The media type definitions SHOULD be in compliance with RFC6838.	FOSSology widely use "application/json” media type in response
10	Conform to HTTP semantics	Ensure that the web API adheres to the semantic meaning of HTTP methods defined by the HTTP protocol. Utilise the common HTTP methods—GET, POST, PUT, PATCH, and DELETE—to perform operations that correspond to the creation, retrieval, modification, and deletion of resources, aligning with the intended semantics of each method. Advantages- Standardised communication Clarity & Performance	Standard HTTP methods deployed by FOSSology
11	Status Codes	Adhere to standardised HTTP status codes to convey the outcome of API requests accurately. HTTP status codes provide a clear indication of the success, failure, or specific conditions of each request, enabling clients to interpret and handle responses appropriately. Some common status codes are as follows: GET Method: 200: OK 204: No Content 404: Not Found POST Method: 200: OK 201: Created 204: No Content 400: Bad Request PUT Method: 200: OK 201: Created 204: No Content 409: Conflict PATCH Method: 400: Bad Request 409: Conflict 415: Unsupported Media Type DELETE Method: 204: No Content 404: Not Found	When a client submits a GET request to retrieve a resource from a RESTful API, the server responds with a 200 OK status code if the request is successful, along with the requested resource in the response body. In the event that a resource is not found, the server returns a 404 Not Found status code, indicating to the client that the requested resource does not exist. By consistently using appropriate status codes in responses, the API ensures clear and meaningful communication with clients, enhancing usability and reliability.
12	Empty sets in message bodies	Any time the body of a successful response is empty, the status code should be 204 (No Content). For empty sets, such as a response to a filtered request with no items, the status code should still be 204 (No Content), not 200 (OK).	Deleting a user returns 204 (No Content)
13	Consistent Casing Conventions	Adopt consistent casing conventions, such as camelCase or snake_case, for naming identifiers within the API, including resource names, query parameters, and JSON keys for both request and response objects. Advantages- Readability and clarity Alignment with industry standards All field names in the specification are case-sensitive	FOSSology response object using camelCase keys
14	Pagination	Exposing a collection of resources through a single URI can lead to applications fetching large amounts of data when only a subset of the information is required. Instead, the API can allow passing a filter in the query string of the URI, such as page and size, from which only the specific subset required is sent as a response. Advantages- Saves bandwidth Improves user experience	a GET request to /blog?page=2&size=10 would fetch the second page of blogs, with each page containing up to 10 blogs. Pagination headers such as Total Pages, Total Items, and Page Number can also be included in the response to provide clients with metadata about the paginated results.
15	Filtering	Incorporate filtering functionality into the API to allow clients to retrieve specific subsets of resources based on defined criteria. Filtering enables clients to tailor their requests to match their requirements, facilitating efficient data retrieval and enhancing the flexibility of the API. Advantages- Customised data retrieval Enhanced usability	In an e-commerce API, clients may need to retrieve products based on various attributes such as category, price range, or availability status. By implementing filtering functionality, clients can send requests like GET /products?cat=ele&range=100-500 to retrieve electronics products within the specified price range. The API processes the filter parameters and returns only the relevant products, providing clients with the precise data they need for their applications.
16	Input fields	Place input fields in one of the following based on the description: Headers- Use headers for sensitive information or authentication data that should not be visible in URLs or easily accessible to users. They should be light- weight and contain protocol related information rather than business logic. Query Parameters- Use for filtering, sorting, or specifying additional options related to the request, such as pagination parameters or search queries. They should be expressive, intuitive, and self-descriptive to improve usability and readability. Do not include sensitive information here. Body- For large or complex data structures, such as JSON objects or file uploads, use the request body to encapsulate the data. Generally, body is used when the arguments don't have a flat key:value structure. Path- Use path parameters to specify variable parts of the URL path. Include input fields that represent identifiers or resource paths directly in the URL, such as IDs, slugs, or resource names. Cookie- Use cookies for storing stateful information or session tokens on the client side.	Headers to store sensitive info like cookies and Authorization. Query parameters are used like Filtering: /products?type=home Pagination: /products?page=1&limit=20 Sorting: /products?sort=price&order=asc Search: /products?query=laptop Specific to FOSSology, query params can be used to store name, id, shortName etc. Body is used to store heavy payloads like JSON objects, or licenseText in terms of FOSSology. Path is used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId. When a user logs in to the website, the server sets cookies to store the user's preferences. For example, the server sets a cookie with values like lang=en&theme=dark. Each time the user visits a page on the website, the browser automatically sends the cookie along with the request and server response accordingly.
17	Versioning	Versioning enables a web API to indicate the features and resources that it exposes, and a client application can submit requests that are directed to a specific version of a feature or resource. Service names and API-class names should be chosen carefully so that they do not change when products are versioned or rebranded. Advantages- Compatibility Maintenance Documentation	Versioning can have many examples like:
18	Use of Models	Utilise models to encapsulate and represent data structures exchanged between clients and the API. Models serve as structured representations of resources and response data. Advantages- Consistency and standardisation Encapsulation Semantic enforcement	Semantic enforcement in one of the models at FOSSology.
19	Concrete Architecture	Adopt a concrete architecture and directory separation strategy for organising the API codebase. Implementing a clear architectural pattern, such as MVC (Model-View-Controller) or similar, along with structured directory separation, enhances code maintainability, scalability, and overall project structure. Advantages- Code maintainability Team Collaboration	. Folder structure of FOSSology REST API.
20	JSON Representation	With regard to JSON representation property names, and URL query parameters, services should: Choose meaningful and succinct names, Do not reuse any names reserved for other purposes by these guidelines, Avoid internal naming conflicts by reusing names for dissimilar purposes, Use plural nouns for arrays, Use singular nouns for non-arrays, Begin with lowercase letters, Prefer camelCase over snake_cases, Follow SCIM Schema naming when the field represents data from the directory, Be case-sensitive.	In this example: Property names are meaningful and succinct, such as userId, userName, emailAddress, etc. Plural nouns are used for arrays (roles). Singular nouns are used for non-arrays (userId, userName, etc.). Property names begin with lowercase letters and use camelCase. SCIM Schema naming convention is followed where appropriate (userId, userName, emailAddress). The representation is case-sensitive, adhering to the guideline.
21	Date and Time fields	All fields with a date/time should follow ISO 8601 and be in UTC timezone.	The W3C note provides clarification and examples.
22	Cross-Origin Resource Sharing (CORS) Policy	The API service must adhere to CORS specifications, supporting both simple and preflight request flows. The Access-Control-Allow-Origin header should be returned in responses to enable cross-origin resource sharing. Advantages- Security compliance Enforcement of policies	CORS headers returned by FOSSology in a response.
23	Error Handling	Standardise the format and handling of error objects returned by the API to provide consistent and informative error responses to clients. Error objects should include relevant information such as error codes, messages, and additional details to assist developers in troubleshooting and debugging issues. Advantages- Consistency in error responses Better error communication	Example of a good error response. Usually, errors are handled using error middleware.
24	Data Validation	Implement robust data validation mechanisms to ensure the integrity, consistency, and security of incoming data, either by using models or regular expressions. Advantages- Prevents Data Corruption Enhances Security	Data validation using regular expressions as FOSSology
25	Security	Prioritise security measures throughout the design, development, deployment, and maintenance phases of the REST API to mitigate potential threats and vulnerabilities. Security considerations include implementing authentication, authorization, encryption, input validation, rate limiting, and protection against common attacks such as injection, XSS, CSRF, and unauthorised access. Advantages- Data Confidentiality Prevention of Attacks	Authentication middleware at FOSSology
26	Testing	Adopt a comprehensive testing strategy to ensure the reliability, functionality, and performance of the REST API. Implement unit tests, integration tests, and end-to-end tests to validate individual components, interactions between components, and the behaviour of the API as a whole. Testing should cover various scenarios, including positive and negative cases, edge cases, error handling, and concurrency. Advantages- Reliability Enhanced Quality Assurance	Test suite for FOSSology REST API
27	Documentation	Use clear and consistent language, along with structured formats such as OpenAPI Specification (formerly known as Swagger), to organise and present the documentation effectively. Keep the documentation up-to-date with the latest changes and enhancements. Also, API documentation should happen before working on the code, as it provides a solid aim to achieve.	FOSSology REST API documentation being viewed on Swagger editor using openapi.yml file

References

• Open Source Projects
  • FOSSology
  • Rocket.Chat
  • Rocket.Chat-Open-API
  • Meshery
  • Meshery Schemas
• API Discussions at Siemens
• Siemens API Catalogue
• API Design by Microsoft
• Google Cloud API Design
• RESTful API design by Red Hat
• Cisco API Design Guide
• JSON API