The HTTP API can be configured for responses to one or more ESB services.
The service will return different HTTP status codes depedning on the state, there is a configuration option for what it will return when it is operating as Active/Standby.
The URL is in the format
http(s)://<url>:<port>/<serviceName>/<messageName>
The service supports GET POST and OPTIONS.
If the service is in standby it will either not return a response at all, or can be set to return a 503 Service Unavailable response.
There is throttling enabled by default which will allow 1 request every 5 seconds. If this is exceeded then a 429 Too Many Requests response will be returned
To send a message to a service exposed by the HTTP API use a POST request to the url http(s)://<url>:<port>/<serviceName>/<messageName> with a JSON body with the parameters of the request.
An OPTIONS request will return a 204 No Content response.
If authentication is enabled, the api session or authentication header must be present. See below
| Code | Reason | Content |
|---|---|---|
200 OK |
ESB Service responsed successfully | JSON Response from service |
400 Bad Request |
ESB Service responded with an error | JSON Response from service |
401 Unauthorised |
If using Authentication no x-api-session header or bearer token |
No Content |
404 Not Found |
ESB Service unknown/unhandled message | JSON Response from service |
421 Misdirected Request |
Unknown ESB Service or not served by this HTTP API | No Content |
503 Service Unavailable |
ESB Service No Comms | No Content |
Perform a GET request to http(s)://<url>:<port>/healthcheck to check the status of HTTP API
| Code | Reason | Content |
|---|---|---|
204 No Content |
HTTP API is Active | No Content |
503 Service Unavailable |
HTTP API is Standby with 503 response enabled | No Content |
| No Resposne | HTTP API is Standby with no response enabled | No Content |
Perform a GET request to http(s)://<url>:<port>/<serviceName> to check whether the HTTP API is connected to the exposes ESB Service
| Code | Reason | Content |
|---|---|---|
204 No Content |
ESB Service Available | No Content |
421 Misdirected Request |
Unknown ESB Service or not served by this HTTP API | No Content |
503 Service Unavailable |
ESB Service No Comms | No Content |
There are several authentication options.
A login can be performed using a Authorization: Basic <auth> where <auth> is a Base64 encoded string username:password using a user from the Authentication Service.
Which must be sent to http(s)://<url>:<port>/login and will return a 200 OK JSON response:
| Code | Reason | Content |
|---|---|---|
200 OK |
Successful Login | { "sessionId": "00000000-0000-0000-0000-000000000000" } |
401 Unauthorised |
Invalid Credentials | No Content |
403 Forbidden |
User does not have the required permission | No Content |
This needs to be sent on subsequent requests as a x-api-session header.
x-api-session: 00000000-0000-0000-0000-000000000000
Session duration is determined by the authentication service.
You can also send a request to the logout endpoint with the session header to end your session. http(s)://<url>:<port>/logout which must include the x-api-session to know which session to end.
Alternatively a static bearer auth token can be configured in the HTTP API service, which must be sent with a Authorization: Bearer <token> header where <token> is the static token configured in the HTTP API service.