⚙
API Guideline
We have changed the code avoiding the generalization of the validation status code and any error status code. Instead of 500, we added a specific status code that depends on the situation. Below we provide more information:
The server has received the request headers and the client should proceed to send the request body.
The server understands and is willing to comply with the client's request, via the Upgrade message header field, for a change in the application protocol being used on this connection.
The request was successful and the server has returned the requested data.
The request was successful and the server has created a new resource based on the request data.
The request was successful but there is no data to return.
The requested resource has been moved permanently to a new location.
The requested resource can be found at a different location temporarily.
The requested resource has not been modified since the last time it was accessed.
The request was invalid or could not be understood by the server.
The request requires user authentication.
The request is valid but the server refuses to respond due to lack of permission.
The requested resource could not be found on the server.
The request was well-formed, but the server could not process it because it contains invalid data.
The server encountered an unexpected condition that prevented it from fulfilling the request.
The server received an invalid response from an upstream server while trying to fulfill the request.
The server is currently unable to handle the request due to a temporary overload or maintenance.
For validation errors, the 422 unprocessable Entity status code is commonly used, which indicates that the request was well-formed, but contains invalid data. This could include missing or invalid parameters, incorrect data types, or other issues with the data in the request. A JSON payload could be returned with more details about the validation error.
For success with empty data, the 204 No Content status code can be used, indicating that the request was successful, but there is no data to return. This can be useful in cases where the client is performing a DELETE or PUT request, where the server doesn't need to return any additional data.
The HTTP 202 Accepted status code indicates that the request has been accepted but has not yet been processed. This status code is often used in APIs to indicate that the server needs more time to process the request or that the request has been queued for processing.
For example, in the context of the Guardian API (https://github.com/hashgraph/guardian), the 202 status code could be used when submitting a new transaction or request to the network. The API could immediately return a 202 response indicating that the request has been received and is being processed, and include a link or other information that the client can use to check the status of the request later.
RESTful APIs are designed around resources, and using consistent naming conventions for resources, HTTP verbs, and query parameters can make your API easier to understand and use. Here are some guidelines for naming conventions in a RESTful API:
Use nouns to represent resources in your API. For example, if you are building an API for managing products, you might use the endpoint /products to represent the collection of all products.
Use plural nouns for collection resources. For example, you might use /products to represent a collection of products.
Use singular nouns for individual resources. For example, you might use /products/{productId} to represent a specific product.
Use hyphens to separate words in resource names. For example, you might use /user-profiles to represent a collection of user profiles.
Use HTTP verbs to represent actions on resources. Here are some common HTTP verbs and their actions:
GET:
Retrieve a resource or a collection of resources.
POST:
Create a new resource.
PUT:
Update an existing resource.
DELETE:
Delete a resource.
For example, you might use GET /products to retrieve a list of products, and POST /products to create a new product.
Use query parameters to filter, sort, or paginate resources.
Here are some guidelines for naming query parameters:
- 1.Use camelCase or snake_case for query parameter names.
- 2.Be consistent within your API in the use of query parameter names.
- 3.Use standard parameter names such as sort_by, page, or limit whenever possible.
For example, you might use /products?sort_by=name or /products?sortBy=name to sort products by name.
By following these naming conventions, you can create a consistent and easy-to-use API that will be intuitive for developers to use and understand.
For a complete documentation of name conventions you can follow the recommendations described in this website: https://restfulapi.net/resource-naming/
Last modified 1mo ago