Check it out! Get more templates! π
Last UpdateοΌ16/09/2024
Metta's Creations | Notion Template Creator
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>
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.
"object" Property): Each top-level resource in a JSON response has an "object" property, which indicates the type of the resource. This is useful for determining the nature of the resource being returned. Examples include:
"database": Represents a database resource."page": Represents a page resource."user": Represents a user resource."block": Represents a block resource."id" Property): Resources are uniquely identified by a UUIDv4 "id" property. This ID can be used to reference the resource in subsequent API requests. Note that when making requests, you may omit dashes from the ID if copying it directly from a Notion URL. For example:
"123e4567-e89b-12d3-a456-426614174000""123e4567e89b12d3a456426614174000"snake_case): Property names within the JSON responses are formatted using snake_case. This convention is consistent across different types of resources. For example:
"created_time": Represents the creation time of a resource."last_edited_by": Represents the user who last edited the resource."page_id": Represents the ID of a page.YYYY-MM-DDTHH:MM:SS.sssZ. Example: "2024-09-16T14:45:30.000Z"YYYY-MM-DD. Example: "2024-09-16""") to represent a lack of value, you should use null to explicitly indicate that the value is unset. This applies to properties like URLs or rich text fields:
"url": """url": nullThese conventions help ensure that the data exchanged with the API is both consistent and easily interpreted.
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.
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 */ ]
}
| 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. |
| 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" } ] |
To ensure fair usage and maintain performance, the API enforces rate and size limits on requests.
The API imposes rate limits to prevent abuse and ensure equitable access.
429 Rate Limit Exceeded error. This indicates that you have sent too many requests in a given time frame.<aside> β Rate Limits May Change
</aside>
The API enforces limits on the size of request parameters and depths.
| --- | --- | --- |
Requests that exceed these limits will trigger a 400 Validation Error, indicating that the request cannot be processed due to size constraints.
HTTP status codes provide critical information regarding the outcome of your API request. Understanding these codes helps in diagnosing issues and handling errors effectively.
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 objects represent individual posts within the API. They provide detailed information about specific posts.