Getting Started with the API

Introduction

The DigitalChalk REST API enables you to access and manage much of your organization’s data via simple HTTP requests. In this guide we will explore some of the conventions and patterns in the API, and attempt to get up and running making requests in just a few minutes.

What You Need To Know

Here’s what you need to know about the DigitalChalk REST API at a glance:

• All requests must be HTTPS; no HTTP connections allowed.
• All data is exchanged in JSON format.
• Authentication via OAuth 2.0
• Sandbox environment accounts available by request
• Base URLs:
  • Production: https://api.digitalchalk.com/api/v5

Getting Started

In order to get started working with the API, you will need developer accounts on the production environment (digitalchalk.com). This is available to existing customers by contacting DigitalChalk Support.

Once you have your developer accounts, you will need to retrieve your OAuth2 access token. This can be found by logging in with the developer account you’ve been given, navigating to the My Account area and clicking the API tab. For more background information on authentication, see Using OAuth 2.0.

Your First Request

Let’s take a look at sending an example HTTP request to retrieve the list of users. For this example we’ll issue the request from a bash shell using the curl utility. Notable things about this request are:

• the Content-Type and Accept headers are both set to application/json
• the Authorization header has the format Bearer followed by your OAuth2 access token

Here’s a look at the request and response.

Request/response via curl

user@host$ curl -X GET -H Authorization:"Bearer ecc4dabc-8fcf-4faa-9d1b-8b3e8571b7da" -H Accept:application/json -H Content-Type:application/json https://api.digitalchalk.com/api/v5/users/
{
    "results": [
        {
            "id": "ff80808141e1f27e0141e2c914ba0001",
            "firstName": "Org",
            "lastName": "Admin",
            "username": "orgadminuser@exampleorg.com",
            "email": "orgadminuser@exampleorg.com",
            "locale": "en",
            "createdDate": "2013-10-23T00:48:50Z",
            "lastLoginDate": "2013-10-23T01:03:51Z"
        },
        {
            "id": "000000003fe3c171013fe3efb9440004",
            "firstName": "Org",
            "lastName": "Dev",
            "username": "orgdevuser@exampleorg.com",
            "email": "orgdevuser@exampleorg.com",
            "locale": "en",
            "createdDate": "2013-07-15T20:05:05Z",
            "lastLoginDate": "2013-07-15T20:07:10Z"
        }
    ]
}

We now have a list of the two users in the organization. We could create new users by issuing a POST request to the users collection url at /api/v5/users, or we could modify existing users by sending PUT requests to /api/v5/users/ff80808141e1f27e0141e2c914ba0001 or /api/v5/users/000000003fe3c171013fe3efb9440004. For more information on working with users, see the Users documentation.

The rest of the examples in the documentation illustrate the actual request and response as they go across the wire for the sake of clarity, with the assumption that you can use your language/framework of choice to generate the illustrated request.

Conventions

Here are some of the quick points that will make your exploration of the API go more smoothly:

• Collections of items tend to be located right off the base URL, with individual items located one level deeper from the collection it belongs to, indicated by its id. For example, the Users collection is located at /api/v5/users and an individual user would be located at /api/v5/users/729ab21ca0010ecaf621294a11c1cdaa, where 729ab21ca0010ecaf621294a11c1cdaa is the id of the user.
• When dealing with collections, the collection of items is always in a results property of the response object. By default, the result will contain a maximum of 15 items. If there is a possibility of more items beyond what is currently returned in the result, the result object will contain a next property with a link to the next set of items in the collection.
• You can always use the parameters limit and offset to change the limit on the number of items returned for one request, and to offset into a subsequent “page” of items. For more information, see Paging Through Results.