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 or has 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.