Skip to content

Latest commit

 

History

History
150 lines (105 loc) · 5.37 KB

integration.md

File metadata and controls

150 lines (105 loc) · 5.37 KB
Raw

Integration documentation

This file contains information of use to developers wanting to integrate a Terracotta-based API into other applications.

The main sections in this document are:

Machine-consumable endpoints

Health check

There is a simple availability check endpoint at /api/ping. This endpoint is intended to be used by monitoring systems to check that the application is available.

  • GET /api/ping
    Returns a 200 OK response with an empty body.

  • GET /api/version
    Returns a 200 OK response with a JSON body containing the current version of the application.

The health check endpoints are not authenticated, and not versioned.

Statistics

Statistics are available at /api/stats.

  • GET /api/stats
    Returns a 200 OK response with a JSON body containing various statistics about the API service.

  • GET /api/stats/history
    Returns a 200 OK response with a JSON body containing historical interval statistics about the API service.

  • GET /api/stats/feed
    Returns a 200 OK response with a status code of 101 Switching Protocols and the Connection header set to Upgrade. This will upgrade the HTTP connection to a WebSocket connection, It will then stream statistics every second in JSON format.

The statistics endpoints are not authenticated, and not versioned.

Types of measurements

There are three main areas for which measurements are tracked and interval-based statistics are calculated. For each of the areas below, cumulative statistics are calculated for each endpoint, and for each HTTP status code returned. Average, maximum, and minimum response times plus sample count are tracked for each interval, and summarised for each period of time configured.

  • Response times
    These are straightforward, being the amount of time taken to respond to a request.

  • Active connections
    The connection average is not a measure of connections over time. For that, the number of requests per period can be used, to work out, for instance, the number of requests per second. That's a trivial calculation. Rather, the connection average is the average number of connections in existence when the system is being used. Periods of zero activity will not affect this average — although obviously they will cause the requests per time period to fall. When each response is served, the number of active connections is sampled, and this is used for the average. This is more important than requests per second for connection monitoring, as it shows the average load profile of the system: in other words, "when the system is actively used, what is the typical number of connections". This is what the average, max, and min are measuring — and so the min will never fall below 1. The importance of these statistics is that they help ensure the system is providing what is needed when it is asked.

  • Memory usage
    The memory usage is the amount of memory used by the application at the end of processing each request and preparing its response. This is not a measure of the peak memory usage whilst processing the request, although if there are multiple simultaneous requests then the point of sampling will naturally coincide with some of the other requests still being processed. Rather, this is a measure at a consistent point in time, so that memory leaks can be detected.

User-facing endpoints

Web application

As Terracotta is a blueprint for both web applications and APIs, it comes with a number of pre-configured endpoints that are intended for consumption by humans using a browser. These are:

  • Protected

    • /: Index page

  • Public

    • /login: Login page
    • /logout: Logout endpoint

Documentation

OpenAPI documentation is available at the following endpoints:

Although Swagger is the typical choice, all three of these UIs are made available to allow for personal preference. They all allow browsing of the API functionality according to the OpenAPI schema generated from the code.

Asset-serving endpoints

There are a number of endpoints that serve static assets. These are:

  • Protected

    • /*path: Any files that exist in the content folder and where the path does not match any registered endpoint

  • Public

    • /css/*path: CSS files
    • /img/*path: Image files
    • /js/*path: JavaScript files
    • /webfonts/*path: Webfont files

Authentication

At present there is no API-specific authentication mechanism, and the only available authentication is for users logging in via a browser.

Authorisation

Terracotta does not come with any authorisation functionality, and so it is up to the developers building upon this foundation to implement authorisation and various permissions as may be required.