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- - 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- | 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- | 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- | 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
|
+
+
+
+[Participants photo 1]
+[Participants photo 2]
+[Participants photo 3]
+Note: The above response also gives the 
+
+[Participants photo 1]
+[Participants photo 2]
+[Participants photo 3]
+
+
+
+
+
