API conventions

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:

• RestAPI Best Practices
• HTTP Status Codes
• HTTP Status Codes 101

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

4.1.2 Use Plural Nouns

• When pointing to collections of resources, always use plural nouns.
  • Correct: /users, /orders
  • Incorrect: /user, /order

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

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

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}

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}

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.