Getting Started with the API

API Overview

The Core API is a RESTful web service that allows you to control Core through a third-party application using JSON for both request and response payloads. Some URLs include inline parameters or query parameters, while some URLs take POST payloads to execute. GET, PUT, POST, and DELETE methods are available, depending on the call.

Access & Authentication

The API is available to all Resolver Enterprise and Professional customers through Swagger, a web-based API browser. Swagger displays a description of the expected usage and response payloads, allowing you to test the calls within the tool.

Users can authenticate through an API key or session token. See the API Authentication section for more information.

Limitations

If you can perform the action through the UI, that same action can be performed via the API. However, some actions may involve numerous API calls or complex payloads, which may require assistance from Resolver Support.

Curl

Swagger automatically generates Curl examples when a command is executed. Curl is a simple command line data utility included with most operating systems, including Windows, Mac, and Linux.

curl -X GET --header 'Accept: application/json' --header 'Authorization: bearer TOKEN

Before executing a Curl command in Windows, ensure all single quotes [ ' ] are replaced with double quotes [ " ]. Attempting to execute a command using single quotes will result in the following error:

curl : (1) Protocol https not supported or disabled in libcurl

When using cURL in Windows PowerShell, make sure to call curl.exe as Microsoft has made Curl a default alias for Invoke-WebRequest.

Swagger

Swagger provides access to all the Core API endpoints, organized by service. Swagger is available through Swagger Docs under Tools in the Core admin settings or directly at https://YOUR_ENVIRONEMT.resolver.com/api?.

Tips:

  • Clicking a resource will reveal the available endpoints. Clicking an endpoint with a GET method will display an example response body and any parameters.
  • Clicking the Example Value box will copy its contents into the body field where you can configure it as needed.
  • Some endpoints include an Example Value, which displays a sample response and/or body parameters. Clicking Example Value in the Parameters section will copy its contents into the body field.
  • Clicking Model beside Example Value will display the data types and whether or not they're optional. Hovering your cursor over these data types will display additional requirements, if any, such as minimum or maximum number of characters.

HTTP Methods & Responses

HTTP Methods
Http VerbDescriptionExample
GETRetrieves a resource.The GET /object/field endpoint in the fields resource retrieves a list of all fields.
POSTCreates a new resource in a collection.The POST /creation/creation endpoint in the objects resource creates a new object.
PUTUpdates an existing resource.The PUT /object/emailTemplate/{id} endpoint in the emailTemplate resource updates one or more elements in an email template.
DELETEDeletes a resource.The DELETE /data/file/{id} endpoint in the file resource deletes a file.
Response Codes
Response CodeDescription
200 OKThe request was successful. For the GET method, details of the resource has been returned in the Response Body. For PUT, POST, or DELETE a description of the action is returned in the Response Body.
204 No ContentThe request was successful, but no content is returned in the Response Body.
400 Bad RequestThe server couldn't understand the request due to an invalid parameter or syntax.
401 UnauthorizedThe client is not authenticated and the response was not completed.
403 ForbiddenThe client doesn't have permission to access the content.
404 Not FoundThe server couldn't find the requested resource. 
422 Unprocessable Entity (WebDAV)The request was well-formed, but the server was unable to process the request due to syntax errors.
500 Internal Server ErrorAn internal error occurred.
503 Service UnavailableThe server can't currently handle the request.

External, Internal & Unique IDs

Most elements in Core, such as objects, fields, reports, relationships, and configuration elements, etc., are assigned an internal ID and an external reference ID, which represents these elements in the API when making calls. Some elements, like fields and object types, are also assigned a unique ID, which helps end-users identify them in Core.

Because external reference IDs don't change when moving them from one org to another, it's recommended that external reference IDs are used when testing and using an integration, using the following approach:

  1. Write the integration using the retrieved external reference IDs.
  2. Retrieve the object type data and store it.
  3. If object types' internal IDs are necessary for a particular endpoint, cross-reference them using the external reference IDs.

See the sections below for more detailed information on internal IDs and external reference IDs.

Internal IDs

  • Intended for internal use.
  • Created for most elements within Core.
  • Automatically assigned.
  • Numeric.
  • Cannot be modified.
  • Visible in Swagger and the URL when viewing associated admin settings in Core.

An object type's internal ID in the URL.

External Reference IDs

  • Also known as external ref IDs.
  • Created for most elements within Core.
  • Alphanumeric.
  • Unique within your org.
  • Can only be modified from Swagger.

Objects

  • Intended for cross-referencing records with external systems.
  • Automatically assigned a unique MD5 hash when created in Core.
  • Imported objects must be assigned a new external reference ID upon import.
  • Can be retrieved from Swagger or from the External Reference ID property on a report table.

Configuration Elements

  • Intended to maintain the relationships between configuration components across multiple orgs with the same configuration (i.e., sandboxes and production orgs).
  • Automatically assigned when created.
  • Preserved when exporting and importing a configuration file from one org to another, but assigned a new internal ID upon import.
  • Visible only in Swagger.

Examples

 GET  /object/report
{
  "data": [
    {
      "id": 9017, <--Report internal ID
      "name": "Risks & Controls By Location",
      "description": "",
      "nameKey": "app:report:name:820c6f98-b82d-496f-9df2-2e2da44a866f",
      "descriptionKey": "app:report:description:231e091c-296b-43bf-a2d9-91a5eca5913b",
      "objectTypeId": 4211,
      "created": "2019-12-09T19:06:56.042Z",
      "modified": "2019-12-09T19:14:58.577Z",
      "org": 46,
      "externalRefId": "8e197f22-774f-459f-b9a1-a087055c1fb7", <--Report external reference ID
      "type": 1,
      "showArchiveData": false,
      "nestloop": "org"
    }
 GET  /object/objectType/{id}
{
  "id": 2373, <--Object type Internal ID
  "name": "Incident",
  "pluralName": "Incidents",
  "description": "",
  "monogram": "INC",
  "nameKey": "app:objectType:name:5ac171c8-69e2-4b7e-aa9a-0ce17c22aa2a",
  "descriptionKey": "app:objectType:description:e130ff47-cf9a-419c-8e74-f70e4ee504f7",
  "pluralNameKey": "app:objectType:pluralName:552ff26a-abea-49ed-9f08-c4dd6e70fdec",
  "monogramKey": "app:objectType:monogram:998fd41f-9cd5-42fd-ad61-d08aee707574",
  "color": "#fff57a",
  "objectLifeCycleId": 2490,
  "externalRefId": "Incident", <--Object type External Reference ID
  "created": "2017-12-14T20:28:06.519Z",
  "modified": "2019-02-07T15:18:02.255Z",
  "nextElement": 34,
  "org": 8,
  "assessment": false,
  "anchor": null,
  "anchorRelationship": null,
  "dataDefinitionId": null
}
 GET  /data/object
    {
      "id": 758, <--Object internal ID
      "name": "Service agreements are maintained for hardware and software",
      "description": "Service agreements are maintained for hardware and software to ensure support during a disaster.",
      "externalRefId": "CON-13:1", <--Object external reference ID
      "uniqueId": "13.1", <--Object Unique ID
      "objectTypeId": 4188,
      "evaluations": {
        "12339": {
          "value": null
        }