Prism API

The Prism API provides near real-time information about infrastructure.

Entities

Prism collects data on the following entities:

• Instances
• Security Groups
• Stages
• Stacks
• Apps
• Buckets
• VPCs
• AWS Accounts

For a full list of prism endpoints, head to https://prism.gutools.co.uk/

Endpoints

The endpoints on Prism all have a similar structure for querying.

Fields that are prefixed with an _ control the query format in some way - they are meta paramters. Fields that are not prefixed with an _ are interpreted as field filters. Field filters are only useful when the endpoint returns an array of objects, and they are used to filter the objects that are returned. You simply add a query parameter with the same name as a top level field and the parameter value will be used to find matching objects.

Some simple examples

Parameter	Description
_brief or _brief=true	return only the ID of objects in a list
_length or _length=true	add companion fields to objects detailing the size of any arrays that are members of the object
stage=TEST	return objects whose stage field has the value of TEST
stage!=TEST	invert - return objects whose stage field does not have the value of TEST
role~=id.*	regexs - return objects whose role field matches the regular expression id.* (i.e. starts with id)
role!~=id.*	inverted regex - return objects whose role field does not match the regular expression
stage=TEST&role~=id.*	multiple fields - an exact match of stage and a regex match of role; this returns objects whose stage field has value of TEST AND whose role field matches the regular expression
stage=TEST&stage=CODE	fields can be specified twice - here we return objects whose stage field has the value of TEST OR CODE
stage!=TEST&stage!=CODE	this makes no sense - here we return objects whose stage field has a value that is not TEST OR not CODE (i.e. all objects)
tag.MongoReplSet=prodprv1	Nested fields can be filtered using periods to separate the fields

Note that multiple filters for the same field have the sense of an OR operation and then the filters for each individual field have the sense of an AND operation.

Response format

A typical Prism response includes the following top level fields:

• status - success or error from the API itself
• lastUpdated - an ISO date indicating the time that the underlying sources were last crawled successfully
• stale - whether prism believes that the data is stale based on the configured shelf life of sources
• staleSources - a list of any sources that haven't been crawled successfully but may have contributed to the API response
• data - the API response
• sources - the list of sources that were interrogated to assemble the response

Adding an AWS account to Prism

• Create a new stack with cloudformation/prism-role.template. In the AWS account requiring Prism. Give it a Stack Name of PrismAccess. When prompted add the Prism account parameter. The format is arn:aws:iam::<account-number>:root, please ask a Guardian developer for the account-number.
• The output of the stack created is a Key named Role. Take the value of Role (arn:aws:iam:[account-number]/PrismAccess-PrismRole-[code]) and add it the spreadsheet listing all AWS Role values (ask a fellow Guardian developer for access to the sheet).
• In DeployTools AWS account go the config-deploy DynamoDB table. Select the App prism, Stage PROD item. Choose Text view. Details of the AWS account requiring prism will need to be added here. There are many examples to follow, the format of the name must be the [aws-account-name].role (we strongly recommend that this matches the short name used by janus) with the output Role value of the step above. Save and close.
• Re-deploy latest prism for the changes to be picked up.

Using prism from the command line

There is a ruby gem that allows you to query the api from the command line.

Running locally

1. Get Deploy Tools Janus credentials.

2. Ensure you are running Java 11

3. Run sbt

4. Start the application: sbt:prism> run

Once the sever has started, the webapp is accessible at http://localhost:9000/