Quick Start

Prerequisites

The following are required to invoke the API:

• A client ID and client secret. Refer to the Client ID and client secret topic for more information.
• If you have not already done so, be sure to understand the basic structure of our API outlined in the Foundations topic.

Call the API

Before you make an API call, it is helpful to understand the flow typical of every interaction between an application and the API. After the flow is described, we move on to exercises and code examples.

Anatomy of an API call

Every API call follows this basic flow:

1. Your application requests and receives an OAuth 2.0 token from the authentication server.
2. Your application invokes the API by making a properly-formatted call consisting of an verb (HTTP method) and a noun (API resource in the form of a URL) along with all necessary HTTP headers, parameters, and any required JSON body.
3. Your authorization token is validated.
4. If valid, the system receives and processes your application's API request.
5. The system returns an API response to your application.

Exercises

The following exercises illustrate simple calls against the API. If you have access to the API, feel free to follow along and try out a call yourself.

Generate a token

Note: This exercise uses the Postman extension for Google Chrome.

Note: If you are using a token provided by a federated identity management system, include the federated token as your access_token value just as you would use a normally-generated access_token.

To obtain an access token:

1. Open Postman

2. Create and Save a Request

3. Change the METHOD to POST

4. Add the authentication URL: https://<<hostName>>/api/authentication/access_token

   Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL.

5. Select Headers and add the following key/value pairs:

   • Content-Type : application/x-www-form-urlencoded

6. Select Body

7. Choose content type x-www-form-urlencoded

8. Add the following key/value pairs:

   • username : <<username>>
   • password : <<password>>
   • client_id : <<client ID>>
   • client_secret : <<client password>>
   • grant_type : password
   • auth_chain : OAuthLdapService

9. Select Send to generate and receive an access token

   Note: You should select and copy your access token before you leave this screen.

Refer to the Authentication and security topic for more information about generating and refreshing an access token.

Call an API resource

Once you have an access token, you're ready to call an API resource. The following exercises step you through a set of sample calls.

First exercise

Note: This exercise uses the Postman extension for Google Chrome.

Note: If you are using a token provided by a federated identity management system, include the federated token as your access_token value just as you would use a normally-generated access_token.

This exercise calls the Retrieve Person by ID operation using the GET HTTP method.

To call the API:

1. Open Postman

2. Ensure the METHOD is GET

3. Add the URL: https://<<hostName>>/api/v1/commons/persons/<<personId>>

   Note: The URL is composed of two parts: a root (https://<<hostName>>/api) and an endpoint (/v1/commons/persons/<<personId>>). The Developer Hub documents all available endpoints.

   Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL and <<personId>> with a valid person number.

4. Select Headers and add the following key/value pairs:

• content-type : application/json

• Authorization : <<access_token>>

  Note: Replace <<access_token>> with the token generated during the Generate a token exercise.

5. Select Send to call the API

This call returns a response body similar to the following example:

{
    "personIdentity": {
        "personKey": 210
    },
    "personInformation": {
        "accessAssignment": {},
        "employmentStatusList": [
            {
                "effectiveDate": "2016-08-13",
                "employmentStatusName": "Active",
                "expirationDate": "3000-01-01"
            }
        ],
        "expectedHoursList": [
            {
                "quantity": 8,
                "timePeriodTypeName": "Daily"
            },
            {
                "quantity": 40,
                "timePeriodTypeName": "Weekly"
            },
            {
                "quantity": 80,
                "timePeriodTypeName": "Pay Period"
            }
        ],
...
}

Second exercise

Note: This exercise uses the Postman extension for Google Chrome.

Note: If you are using a token provided by a federated identity management system, include the federated token as your access_token value just as you would use a normally-generated access_token.

This exercise calls the Retrieve Aggregated Data operation using the POST HTTP method and a JSON request body.

To call the API:

1. Open Postman

2. Ensure the METHOD is POST

3. Add the URL: https://<<hostName>>/api/v1/commons/data/multi_read

   Note: The URL is composed of two parts: a root (https://<<hostName>>/api) and an endpoint (/v1/commons/data/multi_read). The Developer Hub documents all available endpoints.

   Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL.

4. Select Headers and add the following key/value pairs:

• content-type : application/json

• Authorization : <<access_token>>

  Note: Replace <<access_token>> with the token generated during the Generate a token exercise.

5. Select Body

6. Choose body type raw

7. Add the call body

{
  "select": [
    {"key": "EMP_COMMON_FULL_NAME"},
    {"key": "EMP_COMMON_PRIMARY_JOB"},
    {"key": "EMP_COMMON_PRIMARY_ORG"},
    {"key": "PEOPLE_HIRE_DATE"}],
  "from": {
    "view": "EMP",
    "employeeSet": {
      "hyperfind": {
        "id": "1"
      },
      "dateRange": {
        "symbolicPeriod": {
          "id": 5
        }
      }
    }
  },
  "where": [
    {
      "key": "EMP_COMMON_PRIMARY_JOB",
      "operator": "STARTS_WITH",
      "values": [
        "Apprentice"
      ]
    }
  ]
}

8. Select Send to call the API

This call returns a response body similar to the following example:

{
    "metadata": {
        "lastRefreshed": "2017-10-18T14:45:23.713785328",
        "numNodes": "39",
        "metadataKey": "ce1ed033-3ccb-4d61-90c6-abd49de4eca0",
        "cacheKey": "ce1ed033-3ccb-4d61-90c6-abd49de4eca0",
        "totalNodes": "39",
        "totalElements": "39"
    },
    "data": {
        "key": {
            "ROOT": "-1"
        },
        "coreEntityKey": {},
        "attributes": [],
        "children": [
            {
                "key": {
                    "PEOPLE": "91"
                },
                "coreEntityKey": {
                    "EMP": {
                        "id": "91"
                    }
                },
...
}

Code examples

• Request Type: HTTP GET
• Content Type: application/json
• External URL: https://<<hostName>>/api/v1/commons/persons/<<personId>>

The following code examples demonstrate an API call.

cURL

curl -X GET \
  https://<<hostName>>/api/v1/commons/persons/<<personId>> \
  -H 'authorization: <<access_token>>' \
  -H 'content-type: application/json'

Java OkHttp

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://<<hostName>>/api/v1/commons/persons/<<personId>>")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "<<access_token>>")
  .build();

Response response = client.newCall(request).execute();

This call returns a response body similar to the following example:

{
    "personIdentity": {
        "personKey": 210
    },
...
}