💠 GENERIC

INTRODUCTION

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

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

Top-Level Resource Type ("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.
Resource Identification ("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:
- Full UUID: "123e4567-e89b-12d3-a456-426614174000"
- Omitted dashes: "123e4567e89b12d3a456426614174000"
Property Naming (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.
Temporal Values (ISO 8601 Encoding): Temporal values, such as dates and datetimes, are encoded using the ISO 8601 standard. This ensures a consistent and clear format for timestamps:
- Datetime: Includes both date and time, with the format YYYY-MM-DDTHH:MM:SS.sssZ. Example: "2024-09-16T14:45:30.000Z"
- Date: Includes only the date, with the format YYYY-MM-DD. Example: "2024-09-16"
Handling Empty Strings: The API does not support empty strings for certain properties. Instead of using an empty string ("") 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:
- Invalid: "url": ""
- Valid: "url": null

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:

curl -X GET "https://api.example.com/users"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample using JavaScript SDK:

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.

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.	true (if more items exist) / false (if no more items)
next_cursor	string	A cursor token used to retrieve the next page of results.	"abc123xyz"
object	"list"	Specifies the type of the object returned in the response.	"list"
results	array of objects	An array of items returned by the endpoint.	[ { "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.

Rate Limit: The average rate limit is 5 requests per second per user.
Exceeding Limits: If you exceed the rate limits, the API will return a 429 Rate Limit Exceeded error.

SIZE LIMITS

Property	Size Limit	Description
Request Body Size	10 MB	Maximum size of the request body.
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.

STATUS CODE

SUCCESS CODE

HTTP Status	Description	Detail
200 OK	Successfully processed request.	The server successfully processed the request.

ERROR CODES

HTTP Status	Code	Message	Description
400 Bad Request	invalid_request	The request format is incorrect.	The request format or syntax is invalid.
401 Unauthorized	unauthorized	Authentication failed or token expired.	The authentication credentials provided are either invalid or have expired.
404 Not Found	not_found	Resource not found.	The requested resource does not exist on the server.
429 Too Many Requests	rate_limited	Rate limit exceeded.	The number of requests made in a given period exceeds the allowed rate limit.

VERSIONING

API versioning ensures that you can maintain compatibility with the API as it evolves.

Current Version

Format: YYYY-MM-DD

Example: The current API version is 2024-09-16.

Specifying the API Version

To ensure that your requests use a specific version of the API, include the API-Version header in your request.

Example Request:

curl -X GET "https://api.example.com/users"   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"   -H "API-Version: 2024-09-16"

Headers

Authorization: Include your API access token in the Authorization header for authenticated requests.
API-Version: Specify the desired API version in the API-Version header to ensure compatibility with your application.

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.

WHERE USER OBJECT APPEARS

Posts: In the created_by and last_edited_by fields, indicating the user who created or last edited the post.
Comments: In the creator and modifier fields, showing the user who created or modified the comment.

USER FIELDS

Field	Type	Description	Example Value
object*	string	Always "user". Indicates the type of object returned.	"user"
id*	string (UUID)	Unique identifier for the user.	"e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
type	string (optional, enum)	Type of the user. Possible values are "person" and "bot".	"person"
name	string (optional)	Display name of the user.	"Jane Doe"
email	string (optional)	Email address of the user.	"jane.doe@example.com"

POST

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

POST FIELDS

Field	Type	Description	Example Value
id	string (UUID)	Unique identifier for the post.	"a1b2c3d4-e5f6-7890-abcd-1234567890ef"
title	string	Title of the post.	"Introduction to REST APIs"
content	string	Main content of the post.	"This is a detailed guide on REST APIs."
created_at	string (ISO 8601)	Timestamp when the post was created.	"2024-09-16T12:00:00Z"

FILE

File objects provide metadata for files within the API. They are used to describe file details and access information.

FILE FIELDS

Field	Type	Description	Example Value
type	string	Type of the file (e.g., "external", "internal").	"external"
url	string	URL where the file can be accessed.	"https://example.com/file.png"
expiry_time	string (ISO 8601)	Expiry time for the file URL.	"2024-09-16T14:00:00Z"