Dartmouth API Developer Portal

Tasks - Public API

Time-consuming operations (e.g. PATCH /people) are queued and return immediately with a 202 status code and a path to the /tasks API in the Location header including the ID of the queued task (e.g. Location=/api/tasks/5c4f0775a165328794acd48a) . Client applications can use the GET /tasks/{id} API to monitor operation status.

Each resource that supports time-consuming operations has a task queue and an associated worker that monitors the queue. The worker uses the GET /tasks/{id} API to get the data required to complete the task and then uses the PATCH /tasks/{id} API to update task status.

This architecture is illustrated below:

1. iPaaS Client requests PATCH /people

   • Key Owner: App service account (e.g. chosen name)
   • Scope: people:write.sensitive
   • Blueprint creates task document in Mongo
   • Blueprint sends task.id to rabbitMQ
   • Blueprint returns 202 with task.id in Location header when any non-native attrs are created/updated
   • Blueprint returns 200 with object in payload when only native attrs are created/updated

2. iPaaS Client requests GET /tasks/{task.id}

   • Key Owner: App service account (e.g. chosen name)
   • Scope: (none, uses "self" attribute release)
   • Blueprint returns 200 with current status of job and resource URL (i.e. path)

3. People worker gets message (task.id) from rabbitmq

   • rabbitmq account: specific per resource (e.g. people will have its own credentials)

4. People worker requests GET /tasks/{task.id}

   • Key Owner: People worker service account
   • Scope: tasks:people:write
   • Blueprint returns 200 with all task details (status, payload, resource ID, etc.)

5. People worker updates source systems (e.g. Banner)

6. People worker updates cache

7. People worker requests PATCH /tasks

   • Key Owner: People worker service account
   • Scope: tasks:people:write
   • Payload includes path (URL) and status=completed
   • Blueprint returns 200 with all task details (status, payload, resource ID, etc.)

8. People worker requests POST /resource_changes

   • Key Owner: People worker service account (CURRENTLY USING API_KEY_PRIV)
   • Scope: resource_changes:write
   • Blueprint returns 200 with empty payload (i.e., {})

9. People worker deletes message from rabbitmq

   • rabbitmq account: specific per resource (e.g. people will have its own credentials)

Tasks API Requests

For all endpoints, an HTTP status code of 200 indicates success, a 404 code indicates that the task was not found, and a 500 code indicates a bad request. Payload returned with a 500 response contains a descriptive message as to why the request was considered bad.

Client Requesting Task Status

Required Headers - Client

`Authorization: Bearer {jwt}`

Required Scope - Client

No scope is required for this API endpoint. A client only has access to tasks created on its behalf.

Returns - Client

Task status:

{
    "status": "complete",
    "completed_date": "2019-01-08T16:20:45Z",
    "path": "/api/people/d35022g"
}

Worker Requesting Task Status

Required Headers - Worker

`Authorization: Bearer {jwt}`

Required Scope - Worker

Returns - Worker

All task attributes:

{
    "resource": "sample.cars",
    "action": "POST",
    "resource_id": "5c486b86b031b60c4c47180f",
    "payload": {
        "make": "Yugo",
        "model": "Junk"
    },
    "requester": {
        "sub": "f003ghc",
        "aud": "https://localhost",
        "scope": "urn:dartmouth:tasks:sample.cars:write urn:dartmouth:sample.cars:private urn:dartmouth:sample.cars:read urn:dartmouth:sample.cars:read.sensitive urn:dartmouth:sample.cars:write",
        "iss": "https://localhost:8382/api/jwt",
        "name": "Integration Test User",
        "exp": 1533955407,
        "iat": 1533933807,
        "email": "Integration.Test.User@Dartmouth.edu"
    },
    "status": "accepted",
    "request_date": "2019-01-23T13:26:30Z",
    "completed_date": null,
    "path": null,
    "worker_data": null,
    "id": "5c486b86b031b60c4c471810"
}

Worker Updating Task Status

Required Headers - Worker Updating Task Status

`Authorization: Bearer {jwt}`

Required Scope - Worker Updating Task Status

Required Body - Worker Updating Task Status

The request body must contain a valid JSON object containing one or more of the the following attributes: status, completed_date, or path:

{
    "status": "complete",
    "completed_date": "2019-01-08T16:20:45Z",
    "path": "/api/people/d35022g"
}

Returns - Worker Updating Task Status

The updated task is returned:

{
    "resource": "sample.cars",
    "action": "POST",
    "resource_id": "5c486852b031b60c4c47180d",
    "payload": {
        "make": "Yugo",
        "model": "Junk"
    },
    "requester": {
        "sub": "f003ghc",
        "aud": "https://localhost",
        "scope": "urn:dartmouth:tasks:sample.cars:write urn:dartmouth:sample.cars:private urn:dartmouth:sample.cars:read urn:dartmouth:sample.cars:read.sensitive urn:dartmouth:sample.cars:write",
        "iss": "https://localhost:8382/api/jwt",
        "name": "Integration Test User",
        "exp": 1533955407,
        "iat": 1533933807,
        "email": "Integration.Test.User@Dartmouth.edu"
    },
    "status": "complete",
    "request_date": "2019-01-23T13:12:50Z",
    "completed_date": "2019-01-08T16:20:45Z",
    "path": "/api/sample/cars/5c486852b031b60c4c47180d",
    "worker_data": null,
    "id": "5c486853b031b60c4c47180e"
}