API Conventions

PriceShape's API allows you to directly integrate your own systems with PriceShape's pricing data.

Each API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. One section of endpoints allow full CRUD'ing of whole collections and the items within them, while other endpoints provide more convenient querying logic across several resources.

REST Principles

The API strives to follow the principles of REST. In particular:

Uniform Interface: enforce a consistent and standardized API making it easy to use and navigate.

Endpoints represent resources: a resource can be any named piece of our domain model and resources are uniquely identified by URLs. A resource may, when needed, be represented in different formats but we default to JSON.

HTTP methods used to manipulate resources: we map GET, POST, PUT, DELETE, PATCH to the different actions of CRUD’ing a resource.

Endpoints use nous rather than verbs: endpoints are named like /products/:upi rather than /getProducts/:upi.

Use nesting for hierarchical relationships: products are defined in the scope of a feed: /feeds/:feedId/products/:upi.

Graceful error handling: HTTP status code conventions enforced along with meaning error response bodies.

Support filtering and sorting: all collection resources include meaningful query parameters: /products/history?feed=<feed1,feed2>&upi=<upi>.

Versioning: API versioned using dediciated HTTP header.

Use HATEOAS: API is navigable through links between related resources and actions along with pagination links.

Resource naming

Each resource and its query parameters are named according to the following conventions:

Resources are nouns, products, and hyphens are used for composition, input-feeds.

Query parameters are nouns or verbs, offset, and underscores are used for composition, sort_by.

Fields referenced in a query parameter are nouns, sort_by=type, and use camelCase for composition, sort_by=createdAt.

HTTP methods

The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are GET, POST, DELETE, and PATCH. The API documentation provides the HTTP method for every endpoint.

Where possible, the PriceShape API strives to use an appropriate HTTP method for each action.

GET: Used for retrieving resources.

POST: Used for creating resources.

PATCH: Used for updating properties of resources.

PUT: Used for replacing resources or collections of resources.

DELETE: Used for deleting resources.

Input validation and error handling

All requests containing a JSON body are expected to have the Content-Type header set to application/json. Likewise, all responses will have the same header.

Every JSON request body is validated against an accompanying JSON Schemas specified for every endpoint within this API documentation. Likewise, every response body also has an accompanying JSON Schema specification. This ensures consistent error response bodies when a request fails to validate:

{
  "errors": [
    {
      code: "invalid_type",
      path: ["fields", "category"],
      received: "number",
      expected: "string"
    }
  ]
}

HATEOAS

The API utilizes the Hypermedia as the engine of application state (HATEOAS) principle to ease navigation between related resources and make it clear which actions can be performed on a given resource. Each resource may include a links property containing absolute URLs to relevant actions and related resources. As a result, clients do not have to construct related URLs by hand but can instead leverage the hypermedia structure presented by the API.

Pagination

All APIs that represent a collection are paginated by default. Any API response that is paginated includes a pagination property with the properties total, max, and offset for describing the current page along with a links property containing the navigation links: previous, self, and next, where previous and next are optional depending on whether there is a previous/next page to fetch.

The example below illustrates how this pagination property looks for a product history response:

{
  "products": [
    {
      "object": "product",
      "gtin": "123456789012",
      "links": {
        "self": "https://..."
      }
    }
  ],
  "pagination": {
    "total": 400,
    "max": 100,
    "offset": 200,
    "links": {
      "previous": "https://api.priceshape.com/products/:upi/history?feed=<feed>&offset=100&max=100",
      "self": "https://api.priceshape.com/products/:upi/history?feed=<feed>&offset=200&max=100",
      "next": "https://api.priceshape.com/products/:upi/history?feed=<feed>&offset=300&max=100"
    }
  }
  "links": {
    "parent": "https://api.priceshape.com/products/:upi"
  }
}

API Versioning

Discover PriceShape's versioning strategy.

API Authentication

Discover how to authenticate into PriceShape's api

REST Principles#

Resource naming#

HTTP methods#

Input validation and error handling#

HATEOAS#

Pagination#