API Design Guidelines

[calebbourg]

Proposal For Adopting a Set of Standardized API Guidelines

Goal:

To define a set of standard conventions that we agree to adhere to in order to build an ergonomic, functional, cohesive API.

Proposed Guidlines

1. General Design Principles
   Utilize JSON API specification for consistent data formatting and structure in cases not covered by these guidelines.
   Employ standard HTTP methods for CRUD operations (GET, POST, PUT, DELETE).
   Name resources with singular nouns and collections with plural nouns (/User for a single user, /Users for a collection ).
   Implement resource identification using unique identifiers (UUID).
   Always use HTTPS. Any attempts to use HTTP should automatically be redirected to HTTPS counterpart.

2. Filtering
   Allow filtering resources by specifying criteria in the query string.
   Support common filter operators like eq, ne, gt, lt, gte, lte,in, and nin.
   Enable filtering multiple attributes using a comma-separated list.
   Use JSON API syntax for filter parameters (e.g., ?filter[name]=John).

3. Pagination
   Implement pagination for large datasets to optimize performance.
   Provide pagination parameters page[number] and page[size] in the query string.
   Include pagination information in the response header (e.g., Link) and meta field.
   Implement cursor-based pagination for efficient handling of large datasets and updates.

4. JSON API Response Format
   Utilize JSON API format for response structure, including:

• data: An object representing the requested resource or collection.
• meta: Additional information about the response.
• errors: An array of error objects if the request fails.

5. HTTP Status Codes
   Utilize standard HTTP status codes to communicate the outcome of the request. Here are some of the most common codes and their appropriate usage:
   200 OK: The request was successful and the requested resource is available in the response.
   201 Created: The request successfully created a new resource.
   202 Accepted: The request has been accepted for processing, but the processing has not yet been completed.
   204 No Content: The request was successful, but there is no content to return in the response.
   301 Moved Permanently: The requested resource has been permanently moved to a new location.
   302 Found: The requested resource has been temporarily moved to a new location.
   400 Bad Request: The request is malformed or contains invalid syntax.
   401 Unauthorized: The request requires authentication and the user is not authorized.
   403 Forbidden: The user is authorized but does not have permission to access the requested resource.
   404 Not Found: The requested resource could not be found.
   405 Method Not Allowed: The requested method is not supported for the requested resource.
   422 Unprocessable Entity: The request was well-formed but the server could not process it due to semantic errors.
   500 Internal Server Error: An unexpected error occurred on the server.
   503 Service Unavailable: The server is currently unavailable.

Generic Examples:
Request (GET with filtering):

GET /api/v1/users?filter[name]=John&filter[age][gt]=18

Response (successful):

{
  "data": [
    {
      "id": 1,
      "type": "users",
      "attributes": {
        "name": "John",
        "age": 25
      },
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total_pages": 2
    }
  }
}

Request (GET with pagination):

GET /api/v1/users?page[number]=2&page[size]=5

Response (successful):

{
  "data": [
    {
      "id": 6,
      "type": "users",
      "attributes": {
        "name": "John",
        "age": 25
      },
    },
    // ... other users
  ],
  "meta": {
    "pagination": {
      "page": 2,
      "per_page": 5,
      "total_pages": 3
    }
  }
}

Request (GET with error):

GET /api/v1/users?filter[invalid_attribute]=invalid_value

Response (error):

{
  "errors": [
    {
      "status": 400,
      "code": "INVALID_FILTER_ATTRIBUTE",
      "title": "Invalid Filter Attribute",
      "detail": "The attribute 'invalid_attribute' is not valid for filtering."
    }
  ]
}

Resources:

• JSON API

[jhodapp]

Thanks for putting this proposal together Caleb. This is an excellent place to start. I've included my suggestions and questions inline below.

Proposal For Adopting a Set of Standardized API Guidelines

Goal:

To define a set of standard conventions that we agree to adhere to in order to build an ergonomic, functional, cohesive API.

Proposed Guidlines

1. General Design Principles
   Utilize JSON API specification for consistent data formatting and structure.
   Employ standard HTTP methods for CRUD operations (GET, POST, PUT, DELETE).
   Name resources with singular nouns and collections with plural nouns.
   Implement resource identification using unique identifiers.

I think it'd be helpful to provide a quick example here similar to how you listed the CRUD operations above. Also linking out to the spec is a helpful addition: https://jsonapi.org/format/#document-resource-identifier-objects

Use HTTPS for secure communication.

Do we just want to say, use HTTPS all the time, and any URL that requests only HTTP should automatically be redirected to the HTTPS version?

2. Filtering

I suggest including this link: https://jsonapi.org/format/#fetching-filtering

Allow filtering resources by specifying criteria in the query string.
Support common filter operators like eq, ne, gt, lt, gte, lte, in, and nin.
Enable filtering multiple attributes using a comma-separated list.
Use JSON API syntax for filter parameters (e.g., ?filter[name]=John).
3. Pagination

I suggest including this link: https://jsonapi.org/format/#fetching-pagination

Implement pagination for large datasets to optimize performance.
Provide pagination parameters page[number] and page[size] in the query string.
Include pagination information in the response header (e.g., Link) and meta field.
Implement cursor-based pagination for efficient handling of large datasets and updates.
4. JSON API Response Format
Utilize JSON API format for response structure, including:

• data: An object representing the requested resource or collection.

I'm guessing that data would be the data that's described here? https://jsonapi.org/format/#fetching-resources-responses-200

• meta: Additional information about the response, including pagination data.

I don't see meta being used to include pagination data in the spec. Is there a reason you're including pagination data in the meta object or am I missing a section in the spec?

• errors: An array of error objects if the request fails.

And meta and errors would follow a similar approach?

Meta:

• Is your idea for us to adhere to this part of the spec for meta?

Errors:

• I see a meta field defined here for error. Is your idea for us to adhere to this part of the spec?

5. HTTP Status Codes

I suggest including this link: https://jsonapi.org/format/#fetching-resources-responses

Utilize standard HTTP status codes to communicate the outcome of the request. Here are some of the most common codes and their appropriate usage:
200 OK: The request was successful and the requested resource is available in the response.
201 Created: The request successfully created a new resource.

I suggest including this link for CREATE of a new resource: https://jsonapi.org/format/#crud-creating-responses
I suggest including this link for UPDATE of a resource: https://jsonapi.org/format/#crud-updating-responses

202 Accepted: The request has been accepted for processing, but the processing has not yet been completed.
204 No Content: The request was successful, but there is no content to return in the response.
301 Moved Permanently: The requested resource has been permanently moved to a new location.
302 Found: The requested resource has been temporarily moved to a new location.
400 Bad Request: The request is malformed or contains invalid syntax.
401 Unauthorized: The request requires authentication and the user is not authorized.
403 Forbidden: The user is authorized but does not have permission to access the requested resource.
404 Not Found: The requested resource could not be found.
405 Method Not Allowed: The requested method is not supported for the requested resource.
422 Unprocessable Entity: The request was well-formed but the server could not process it due to semantic errors.
500 Internal Server Error: An unexpected error occurred on the server.
503 Service Unavailable: The server is currently unavailable.

Generic Examples: Request (GET with filtering):

GET /api/v1/users?filter[name]=John&filter[age][gt]=18

Response (successful):

{
  "data": [
    {
      "id": 1,
      "type": "users",
      "attributes": {
        "name": "John",
        "age": 25
      },
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total_pages": 2
    }
  }
}

Request (GET with pagination):

GET /api/v1/products?page[number]=2&page[size]=5

Response (successful):

{
  "data": [
    {
      "id": 6,
      "type": "products",
      "attributes": {
        "name": "Product 6",
        "description": "Description of product 6"
      },
    },
    // ... other products
  ],
  "meta": {
    "pagination": {
      "page": 2,
      "per_page": 5,
      "total_pages": 3
    }
  }
}

Request (GET with error):

GET /api/v1/orders?filter[invalid_attribute]=invalid_value

Response (error):

{
  "errors": [
    {
      "status": 400,
      "code": "INVALID_FILTER_ATTRIBUTE",
      "title": "Invalid Filter Attribute",
      "detail": "The attribute 'invalid_attribute' is not valid for filtering."
    }
  ]
}

It'd be good to include a CREATE, UPDATE and DELETE example here too

Resources:

• JSON API

[calebbourg]

@jhodapp Thank you for excellent the feedback on this! I made some updates to the guidelines based on your suggestions.

In particular, I modified the first guideline to:

Utilize JSON API specification for consistent data formatting and structure in cases not covered by these guidelines.

as a sort of fallback disclaimer so that we do not need to reiterate the entire spec in our guidelines here. Let me know if that seems adequate to you. Trying to account the inevitable things that will fall through the cracks. This way we'll have something to refer to in those situations.

[jhodapp]

Great thought, I agree there's no need to regurgitate the JSON API spec throughout ours, especially since we'd have to keep the two in sync then. Better to reference the spec in specific parts with a link like you are suggesting.

I updated "products" and "orders" to be "users" just since we don't have the other entity types and it seemed helpful to keep the example entity type consistent through the examples. Let me know if you wanted them to be the other types for a specific reason.

[calebbourg]

Nope that's actually great! Thanks for doing that.

[jhodapp]

Awesome, you're welcome!

Anything else you think we need to add to this guideline at this moment? I think you mentioned wanting to import it into our backend source repo as an architecture design record once a first version solidified?