API conventions - bounswe/bounswe2023group2 GitHub Wiki
1. Introduction
1.1 Purpose of Document
This document aims to set the API standards of DaRP. Coding templates, coding standards, or common best practice code examples are not in the scope of this document.
1.2 Status of Document
Version | Change log | Date |
---|---|---|
1.0 | First release of the document | 24.10.2023 |
1.1 | Successful results simplified | 24.10.2023 |
1.1.1 | Corrections on 1.1 | 27.10.2023 |
2. General Structure & Handling
2.1 Response Handling
- Response codes will indicate the success or failure of an API call.
- On error, the response code and detailed JSON error messages will be returned.
- Teams should use backend error messages to inform the end user.
- The multilingual nature of the system is managed on the backend.
2.2 Response Codes
- API functions should gracefully handle errors and provide appropriate response codes.
- Success: HTTP 200
- Data Not Found: HTTP 404
- Unauthorized: HTTP 401
- System Error: HTTP 500
External Resources:
2.3 Error Messages
Error messages will adhere to our API's JSON structure standard. Base components include:
- ErrorMessage: Detailed error information.
- ErrorData: Specifics on the problematic data supplied by the call (e.g., "Resource 1012002 does not exist").
3. JSON structure
3.1 On successfull calls
Sample response codes to set standards:
3.1.1 GET - Single item (HTTP 200)
Single item response (Note the array structure of data, although it contains only one item):
HTTP/1.1 200
Content-Type: application/json
{
"resources": [
{
"resourceId": 1001,
"name": "shirt",
"color": "red",
"Sizes": [
"1",
"2",
"3"
]
}
]
}
3.1.2 GET - Item List (HTTP 200)
HTTP/1.1 200
Pagination-Count: 100
Pagination-Page: 5
Pagination-Limit: 20
Content-Type: application/json
{
"resources": [
{
"resourceId": 1001,
"name": "shirt",
"color": "red",
"Sizes": [
"1",
"2",
"3"
]
},
{
"resourceId": 1002,
"name": "shirt",
"color": "black",
"Sizes": [
"1",
"2",
"3"
]
}
]
}
Check that, the format for the fetch list and fetch one item should be the same. Both return an array as data, only the API function for "one item" fetch returns an array of size 1.
This is preferred to simplify the client code, as it make possible to use the same data extracting routine for all different ways.
3.1.3 POST - Create New Item (HTTP 201)
The response_code (201) shows the caller that the create item is successful. But still, the created item data is sent back to the caller, for convenience.
HTTP/1.1 201
Location: /v1/items/12
Content-Type: application/json
{
"resources": [
{
"created_by": "mehmetk",
"condition": "used",
"initialQuantity": 1917,
"currentQuantity": 1917,
"type": "Food",
"details": {
"SKT": "11-11-2024"
},
"_id": "653bac2c07dfc8a5050ef7ce"
}
]
}
3.1.4 PUT - Update Item (HTTP 200/204)
3.1.4.1 If updated entity is to be sent after the update
HTTP/1.1 200
Content-Type: application/json
{
"resources": [
{
"_id": "653bac2c07dfc8a5050ef7ce",
"name": "shirt",
"color": "red",
"Sizes": [ "1", "2", "3"]
}
]
}
3.1.4.2 If updated entity is not to be sent after the update
HTTP/1.1 204
3.1.5 DELETE - Item (HTTP 204)
3.1.5.2 If deleted entity is not to be sent after the update
HTTP/1.1 204
3.1.5.2 If deleted entity is to be sent after the update
{
"_id": "653bac2c07dfc8a5050ef7ce"
}
3.2 On failure
Sample response codes to set standards:
3.2.1 GET (HTTP 404)
HTTP/1.1 404
Content-Type: application/json
{
"ErrorMessage": "The user does not exist",
"ErrorDetails: "User: Cezmi Baskın does not exist"
}
3.2.2 DELETE (HTTP 404)
HTTP/1.1 404
Content-Type: application/json
{
"ErrorMessage": "User not deleted",
"ErrorDetails": "User: Cezmi Baskın does not exist"
}
3.2.3 POST (HTTP 400)
HTTP/1.1 404
Content-Type: application/json
{
"ErrorMessage": "User not updated",
"ErrorDetails": "Duplicate record for profile languages for User: Cezmi Baskın"
}
3.2.4 ANY VERB (HTTP 401: Unauthorized access)
HTTP/1.1 401
Content-Type: application/json
{
"ErrorMessage": "User not authorized to do this",
"ErrorDetails": "User Cezmi Baskın can not create resources"
}
3.2.5 ANY VERB (HTTP 401: Login required)
HTTP/1.1 401
Content-Type: application/json
{
"ErrorMessage": "Login required",
"ErrorDetails": "Login to create resources"
}
3.2.6 ANY VERB having authorization problem (invalid session credentials etc)
For this case We don't use the ErrorDetails. By convention, we set the response_code to 401
HTTP/1.1 401
Content-Type: application/json
{
"detail": "Could not validate credentials"
}
4. Naming Conventions
For improved consistency, clarity, and predictability, adhering to a uniform naming convention for our API endpoints is critical. Below are the guidelines to be followed:
4.1 URI Naming Guidelines
4.1.1 Use Lowercase Letters
- URIs should begin with a letter and utilize only lowercase letters.
- Correct:
/users
,/orders
- Incorrect:
/Users
,/Orders
- Correct:
4.1.2 Use Plural Nouns
- When pointing to collections of resources, always use plural nouns.
- Correct:
/users
,/orders
- Incorrect:
/user
,/order
- Correct:
4.1.3 Hyphen Separate Resource Names
- For improved readability in URI paths, separate literals/expressions using a hyphen (
-
).- Correct:
/user-info
,/order-history
- Incorrect:
/userinfo
,/orderhistory
- Correct:
4.1.4 Underscore Separate Query Strings
- Separate literals/expressions in query strings using an underscore (
_
).- Correct:
/users?sort_by=name
,/orders?filter_by_status=completed
- Incorrect:
/users?sort-by=name
,/orders?filter-by-status=completed
- Correct:
4.1.5 Use Sub-resource Collections for Relations
- For indicating a relationship to another collection of resources, sub-resource collections should be placed directly beneath an individual resource.
- Correct:
/users/{user_id}/orders
,/orders/{order_id}/items
- Incorrect:
/users/orders/{user_id}
,/orders/items/{order_id}
- Correct:
4.1.6 Use Top-Level Resources (When Possible)
- To ensure simplicity, aim for limited nesting of resources.
- Correct:
/items/{item_id}
- Incorrect:
/users/{user_id}/items/{item_id}
- Correct:
4.1.7 Avoid Verbs in the URI
-
The HTTP verb should dictate the action, not the URI.
Incorrect Correct GET /getAllUsers GET /users POST /createUser POST /users PUT /updateUser/{id} PUT /users/{id} DELETE /deleteUser/{id} DELETE /users/{id}
It's essential to maintain these conventions across all teams and all parts of the project to ensure the API remains user-friendly, consistent, and easy to maintain.