Access the APIs

Overview of the API

To begin using the Contrast API, you will need to retrieve your API Key from the server. To do this, you will need to log in to your TeamServer account and have the application email you a generated API Key.

  1. Log in to TeamServer
  2. Click the Down arrow next to your login name in the page header
  3. Click on API Key
  4. Click either Email me the current API Key or Rotate the key and email me a new key

Once you have retrieved your API Key, you will set this, along with your authorization credentials, as headers on each request to the API.

Header Value
API Key The API Key retrieved above (Plaintext)
Authorization Base64-encoded credentials (username:service-key)
Accept application/xml, application/json

Sample Request

curl -HAccept:application/json -HAuthorization:test -HAPI-Key:test https://app.contrastsecurity.com/Contrast/api/applications

Sample Response

[
  {
    "links": [
      {
        "rel": "server",
        "method": "GET"
        "href": "https://app.contrastsecurity.com/Contrast/api/application/c0d6b545-6377-483e-8b0c-f2e2e2aa8684/server"
      },
      ...
    ],
    "appId": "c0d6b545-6377-483e-8b0c-f2e2e2aa8684",
    "name": "Test Application"
    ...
  }
]

Data Expansion

Any data enclosed in a HATEOAS link as a GET for a resource can be expanded to be included in the resource result itself. To add a Data Expansion to an API call, you will add the expand parameter to the API Resource call. Each of the resources listed in this documentation lists the data available for expansion under the resource being queried.

Sample Request

curl -HAccept:application/json -HAuthorization:test -HAPI-Key:test https://app.contrastsecurity.com/Contrast/api/applications/c0d6b545-6377-483e-8b0c-f2e2e2aa8684/?expand=server

Sample Response

[
  {
    "links": [ ... ],
    "app-id": "c0d6b545-6377-483e-8b0c-f2e2e2aa8684",
    "name": "Test Applications",
    "short-name": "Test",
    "group-name": null,
    "path": "/test",
    "language": "Java",
    "license": "Trial",
    "lastSeen": 23472983488,
    "server": {
      "server-id": 1,
      "last-startup-message-received": 2/27/2014 17:30:00,
      ...
    }
  }
]

HATEOAS Links

Each API call response includes an array of HATEOAS (Hypermedia as the Engine of Application State) links. The beauty of HATEOAS is that it allows you to interact and construct an API flow solely through the hyperlinks we provide you. You no longer need to hardcode logic into your client in order to use our API. We provide HATEOAS links for each call and for transactions within a call, if available.

Element Description
HREF URL of the related HATEOAS link you can use for subsequent calls to the API.
REL The relation of the link to the current resource you have retrieved.
METHOD The HTTP method to use for the related call.

Example of HATEOAS Links

{
  "links": [
    {
      "href": "https://app.contrastsecurity.com/Contrast/api/applications/c0d6b545-6377-483e-8b0c-f2e2e2aa8684",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://app.contrastsecurity.com/Contrast/api/applications/c0d6b545-6377-483e-8b0c-f2e2e2aa8684/server",
      "rel": "server",
      "method": "GET"
    }
  ]
}

Paging & Filtering

The following parameters can be used for paging and filtering results on GET calls that return multiple results.

Parameter Description
count The number of results to return (default -1 to return all results)
start_index The index within the collection to return as the first result of the page
sort_by The field on which to sort within the returned result (Only Strings, Numbers or Timestamps)
sort_order The direction in which to sort the collection (asc or desc)
curl -HAccept:application/json -HAuthorization:test -HAPI-Key:test https://app.contrastsecurity.com/Contrast/api/applications/?count=10&start_index=11&sort_by=name&sort_order=desc

Additionally, there are also pre-generated filters for filtering data in useful ways. This list will continue to grow as we add more filters based on user feedback and client need.

Resource Type Filter Description
Libraries withCVE Filter out libraries that do not have any CVE's associated with them.

To use a filter on a request, simply add the filter parameter and any parameters required by that filter to the URL.

curl -HAccept:application/json -HAuthorization:test -HAPI-Key:test https://app.contrastsecurity.com/Contrast/api/applications/{app-id}/libraries/?filter=withCVE

Response Codes

Response Status Code Description
200 The operation was successful
404 Resource not found
439 Too Many Requests
500 Server Error