Check it out! Get more templates! 👉

Last Update：16/09/2024

Metta's Creations | Notion Template Creator

💠 GENERIC

INTRODUCTION

This documentation provides a comprehensive guide to understanding and using the [Your API] REST API.

<aside> ❗ To interact with the API, you need an API key. You can obtain your API key from the API settings page. If this is your first time using the API, we recommend starting with the Getting Started Guide to learn how to generate an API key and set up your environment.

</aside>

CONVENTIONS

The base URL for all API requests is https://api.example.com. HTTPS is required for all API interactions.

The API follows RESTful conventions with operations performed using GET, POST, PUT,PATCH , and DELETE requests on various resources. All request and response bodies are encoded as JSON.

JSON CONVENTIONS

These conventions help ensure that the data exchanged with the API is both consistent and easily interpreted.

CODE SAMPLES AND SDK

Request samples are provided for each endpoint using common tools like cURL and code snippets in popular SDKs. You can also use any HTTP client library of your choice.

Sample using cURL:

bash
Copy code
curl -X GET "<https://api.example.com/users>" \\
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample using JavaScript SDK:

javascript
Copy code
const exampleSDK = require('example-sdk');

exampleSDK.users.getAllUsers()
  .then(response => console.log(response))
  .catch(error => console.error(error));

SDKs: Check our SDK repository for various language-specific implementations.

PAGINATION

Endpoints that return lists of objects support cursor-based pagination. By default, ten items are returned per request. Use the next_cursor value from the response to fetch the next page of results.

Example Pagination Response:

{
  "has_more": true,
  "next_cursor": "eyJzIjoiaW5kZXgiLCJwIjoidXNlcnMifQ",
  "object": "list",
  "results": [ /* array of objects */ ]
}

SUPPORTED ENDPOINTS

HTTP Method Endpoint Description
GET /users Retrieve all users.
GET /users/{user_id} Retrieve a specific user.
POST /posts Create a new post.
PUT /posts/{post_id} Update an existing post.
DELETE /posts/{post_id} Delete a specific post.
GET /posts/{post_id}/comments Retrieve comments for a post.
POST /posts/{post_id}/comments Add a new comment to a post.

RESPONSES

Field Type Description Example Value
has_more boolean Indicates whether there are additional items available for retrieval beyond the current page of results. This field helps determine if further requests are necessary to fetch the complete set of items. true (if more items exist) / false (if no more items)
next_cursor string A cursor token used to retrieve the next page of results. This field is provided only when has_more is true. It allows the client to request subsequent pages of results by including this token in the start_cursor parameter of the next request. "abc123xyz”
object "list" Specifies the type of the object returned in the response. For paginated responses, this value is always "list", indicating that the response contains a list of items. This helps in understanding the structure of the response. "list"
results array of objects An array of items returned by the endpoint. Each object in the array represents an individual item in the response. The exact properties and structure of these objects depend on the specific endpoint and resource type. [ { "id": "123", "name": "Item 1", "description": "Description of item 1" }, { "id": "124", "name": "Item 2", "description": "Description of item 2" } ]

REQUEST LIMITS

To ensure fair usage and maintain performance, the API enforces rate and size limits on requests.

RATE LIMITS

The API imposes rate limits to prevent abuse and ensure equitable access.

<aside> ❗ Rate Limits May Change

The rate limits may be adjusted based on system demand and performance metrics. Different tiers of service might have distinct rate limits.

</aside>

SIZE LIMITS

The API enforces limits on the size of request parameters and depths.

Property Size Limit Description
Request Body Size 10 MB Maximum size of the request body. Exceeding this limit will result in a 400 Validation Error.
Rich Text Length 2000 characters Maximum allowable length for rich text fields.
File Size 50 MB Maximum allowable size for file uploads.
Nested Request Depth 5 levels Maximum depth for nested requests.

Requests that exceed these limits will trigger a 400 Validation Error, indicating that the request cannot be processed due to size constraints.

STATUS CODE

HTTP status codes provide critical information regarding the outcome of your API request. Understanding these codes helps in diagnosing issues and handling errors effectively.

SUCCESS CODE

HTTP Status Description Detail
200 OK Successfully processed request. The server successfully processed the request, and the response contains the requested data or confirmation of the action performed.

ERROR CODES

Error responses contain more detail about the error in the response body, in the "code" and "message"properties.

HTTP Status Code Message Description
400 Bad Request invalid_request The request format is incorrect. The request format or syntax is invalid, which prevents the server from understanding and processing it. Verify and correct the request structure.
401 Unauthorized unauthorized Authentication failed or token expired. The authentication credentials provided are either invalid or have expired. Ensure that the token is correct and still valid.
404 Not Found not_found Resource not found. The requested resource does not exist on the server. Confirm that the URL is correct and that the resource is available.
429 Too Many Requests rate_limited Rate limit exceeded. The number of requests made in a given period exceeds the allowed rate limit. Wait before making further requests or optimize your request frequency.

VERSIONING

API versioning ensures that you can maintain compatibility with the API as it evolves. Each version of the API is identified by its release date, allowing for clear tracking and management of changes over time.

Current Version

Specifying the API Version

To ensure that your requests use a specific version of the API, include the API-Version header in your request. This practice helps avoid unexpected changes and ensures consistent behavior from the API.

Example Request:

Headers

By following these guidelines, you can manage API updates and maintain stability in your integration.

🌟 OBJECTS

USERS

User objects represent users within the API. These objects are used in various API responses to provide details about the user involved in different actions.

POST

Post objects represent individual posts within the API. They provide detailed information about specific posts.

FILE