Conventions
The PagePeek API is designed with a RESTful architecture, promoting a clear and structured interaction model between the client and the server. To ensure a consistent and understandable experience while working with our API, we adhere to certain conventions as outlined below:
HTTP Methods
- GET: Retrieve data from the server.
- POST: Send new data to the server.
- PUT: Update existing data on the server.
- DELETE: Remove data from the server.
HTTP Status Codes
We use standard HTTP status codes to indicate the success or failure of an API request.
- 2xx: Success category (e.g., 200 OK, 201 Created).
- 4xx: Client errors category (e.g., 400 Bad Request, 404 Not Found).
- 5xx: Server errors category (e.g., 500 Internal Server Error).
Endpoint Naming
Endpoints are named logically based on the resources they represent. They are structured to be self-explanatory and straightforward.
Example:
/documents/upload
for uploading documents./documents/:document_id/summary
for retrieving a document summary.
URL structure
URLs are constructed in a clear and predictable manner, with resource identifiers and optional parameters to filter, search, or modify the request.
Example:
GET /documents/search?query=financial report 2022
JSON Conventions
The PagePeek API uses the JSON (JavaScript Object Notation) format for request and response bodies. Below are some conventions followed in our JSON structures:
Naming Conventions
Property names are written in
camelCase
.Boolean properties often have
is
orhas
prefixes for readability.
Example:
{
"documentId": "abc123",
"hasAnnotations": true
}
Date and Time
Dates and times are formatted as strings in ISO 8601 format.
Example:
{
"createdAt": "2023-10-01T12:00:00Z"
}
Null Values
Properties with null
values are included in the response body, indicating that the property exists but has no value.
Example:
{
"summary": null
}
Error Objects
In case of an error, a JSON object is returned in the response body containing an error code, message, and additional details.
Examples
{
"error": {
"code": 400,
"message": "Bad Request",
"description": "Your request is missing the 'name' parameter"
}
}
These conventions help ensure that the interaction with the PagePeek API is organized, predictable, and easily understandable, aiding developers in effectively utilizing the API to its full potential.
Last updated