diff --git a/docs/2024/rest/API-guidelines.md b/docs/2024/rest/API-guidelines.md new file mode 100644 index 0000000000..c5bc9460c6 --- /dev/null +++ b/docs/2024/rest/API-guidelines.md @@ -0,0 +1,763 @@ +--- +sidebar_position: 3 +title: REST API Guidelines +author: Divij Sharma +tags: [gsoc24, rest] +--- + + + +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. + +
**#** | +**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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ + 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-
+
|
+ +  + 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:
+
|
+ +  + 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-
+
|
+ +  + 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-
+
|
+ + 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-
+
|
+ + 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:
+
|
+
+
|
+
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-
+
|
+ + 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-
+
|
+ +  + 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-
+
|
+ +  + . + Folder structure of FOSSology REST API. + | +
20 | +**JSON Representation** | +
+ With regard to JSON representation **property names, and URL
+ query parameters, services** should:
+
|
+
+ 
+ In this example:
+
|
+
21 | +**Date and Time fields** | ++ All fields with a date/time should follow **ISO 8601** and be + in UTC timezone. + | ++ The [W3C](https://www.w3.org/TR/NOTE-datetime) 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-
+
|
+ +  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-
+
|
+ +  + 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-
+
|
+ +  + 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-
+
|
+ +  + 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-
+
|
+ +  + 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 + | +