Standard API is a restful HTTP API specification for creating incidents on a force system. Forces need to create an API that implements the specification which is accessible over the internet which iHub can then send submissions to.
The force must stand up an implementation of the Standard API specification. The current Standard API v1 specification can be downloaded from [here].
The Standard API specifies only one endpoint, /incidents, and currently only one HTTP method, POST, which iHub will send submissions to. When a force implementation receives this data it must persist this data before responding back with the required 201 response and payload. Once iHub receives this response it is expected the force has the data and iHub will mark the submission for deletion using it's normal data retention policies for the force. It is expected that force internal retry mechanisms are used for any error scenarios after the 201 response has been returned.
If the force implementation errors in any way before persisting the data it must respond with an error response code and an errors payload as defined in the specification. In this scenario iHub retry mechanisms will attempt to resend the data to the force via Standard API or fallback to an email delivery. More detail on error handling and retries can be found here.
The force Standard API implementation must be exposed to the internet and have a hostname that is resolvable using public DNS. The endpoint must implement TLS 1.2 or above. The endpoint should be served over port 443 but other ports can be used if required.
iHub uses public DNS for name resolution for Standard API endpoints. As such the force implementation must be resolvable using a public DNS.
Force Standard API implementations must support the following authentication methods
- Mutual TLS
- API Key / Secret.
iHub and Standard API utilise Mutual TLS (mTLS) for mutual authentication to ensure transport level authentication. Details of mTLS and how it works can be found here.
The Force must provide the iHub team with the following to support enable the use of mTLS
- Client Certificate
- Client Key
- Key passphrase
- Server Certificate CA chain (only required if the server cert if signed by a public CA)
The forces local CA should be used to create client certificates. Example steps to create a client cert using openssl are shown below.
Generate a key pair.
openssl genrsa -out client_cert_key_filename.key 2048Create a CSR for the client certificate.
openssl req -new \ -key client_cert_key_filename.key -out client_cert_csr_filename.csrCreate a client certificate from the CSR.
openssl x509 -req \ -in client_cert_csr_filename.csr \ -CA root_CA_cert_filename.pem \ -CAkey root_CA_key_filename.key \ -CAcreateserial \ -out client_cert_filename.pem \ -days 730 -sha256S
Standard API also requires that the iHub sends an API client and secret using basic HTTP Authentication. The force need to provide an API Key (username) and Secret (password) for the iHub to use to authenticate.
The iHub sends HTTP requests with the Authorization header than contains the word Basic followed by a space and a base64-encoded string in the format username:password.