API Conventions

• An endpoint represents a collecton of resources. We will always represent resources in plural form (e.g. /reports not /report).
• We will only support producing JSON output in the MVP implementation.
• We will default attribute naming convention to pascal case
• All responses will be compressed using gzip compression.
• Dates will be represented in the following format: yyyy-mm-dd
• Timestamps will be represented in UTC in the following format: yyyy-mm-ddThh:MM:ss.SSSZ
• Percents will be represented as whole numbers (e.g. 23.25, not .2325)
• Decimals will be represented as with a decimal scale of two digits (e.g. 23.25, 23.00, 23.20, 23.02)
• Values which are not available will be represented as null
• The API will support Level 2 of the Richardson Maturity Model. Hypermedia will not be implemented without client feedback. YAGNI!

HTTP Status Codes

Http Status Code	Description
202	The request has been accepted and will be actioned based on the scheduled defined in the message structure
400	Your request was not valid
401	Unauthorized to access resource
403	The server understood your request, but refuses to statisfy it
404	The record requested does not exist or is not in your profile
429	You have been throttled!

---

Requests Message Primitives

In ALL cases, the HTTP POST and PUT will always take the same basic form made up of two attributes: Parameters and Metadata.

Parameters is a JSON object which will provide specific information about the resource to be created. For example, when creating a report, it will contain information to identify the report, the specifics of the output and information about the scheduling.

Metadata is a JSON object which is reserved for the mechanics (usually internal) of a messaging interaction. For example, the BMC listener servers, when publishing a report, may pass tracer and debugging information into the API to get access to specific stats which help with debugging. Those attributes will always be published via Metadata.

{
    "Parameters" : {},
    "Metadata" : {}
}

---

Response Message Primitives

In ALL cases, the HTTP response will contain the following set of attributes: RequestId, StatusCode, Errors, Payload, and Stats.

AttrName	DataType	Nullable	Default
RequestId	uuidv4	false	sys generated
StatusCode	int	false	http status code
Errors	array	true	an array of objects. null if payload exists
Payload	object	true	the output of the report. null if errors exists
Stats	object	true	system generated stats about the request, to include paging, exec times etc.

---

RequestId is the system generated identifier for each request. All system interaction is logged and tagged at the per request level, using this system generated id

StatusCode is the HTTP Status Code (also in the http headers).

Errors is a one-to-many array of error objects representing any problem the system identified during processing a request. An error object will contain an identifier (e.g. attribute name) and the error message associated with the identifier.

Payload is the business data returned in all responses. For client side simplicity, The decision to universally return an array, even when there is only one response is to simplify both the server and client interaction.

Stats is a list of metrics related to the individual execution. Examples: paging statistics, the time it took to generate a benchmark report, debugging flags etc. are examples of Stats

Success Response Example

{
    "RequestId" : "",
    "StatusCode" : 200,
    "Errors" : null,
    "Payload" : [],
    "Stats" : {}
}

Error Response Example

{
    "RequestId" : "",
    "StatusCode" : 400,
    "Errors" : [],
    "Payload" : null,
    "Stats" : {}
}

---