Overview

This documentation covers the BigCo Task Process Service (TPS) web API.

RFC2119 Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Media Type support

All server response bodies and request bodies MUST be valid JSON Media Type messages.

URLs and Operations

Below are the URLs and the operations associated with them.

Tasks

The Task URL (/task/) is the base URL for reading and updating Task objects The table below shows all the Task-related operations, their URLs, methods, and payloads.

Table 1. Task Operations
Operation URL Method Returns Inputs

TaskList

/task/

GET

Task Payload

none

TaskAdd

/task/

POST

Task Payload

[title], [completeFlag]

TaskItem

/task/{id}

GET

Task Payload

none

TaskUpdate

/task/{id}

PUT

Task Payload

[id], [title], [completeFlag]

TaskDelete

/task/{id}

DELETE

Task Payload

none

TaskMarkComplete

/task/completed/{id}

POST

Task Payload

none

TaskAssignUser

/task/assign/{id}

POST

Task Payload

[id], [nick]

TaskFilterByTitle

/task/?Title={title}

GET

Task Payload

none

TaskFilterByStatus

/task/?CompleteFlag={status}

GET

Task Payload

none

TaskFilterByUser

/task/?AssignedUser={nick}

GET

Task Payload

none

Users

The User URL (/user/) is the base URL for reading and updating User objects and supports the following operations:

Table 2. User Operations
Operation URL Method Returns Inputs

UserList

/user/

GET

User Payload

none

UserAdd

/user/

POST

User Payload

[nick], [password], [name]

UserItem

/user/{nick}

GET

User Payload

none

UserUpdate

/user/{nick}

PUT

User Payload

[nick], [name]

UserChangePassword

/user/changepw/{nick}

POST

User Payload

[nick], [oldPass], [newPass], [checkPass]

UserFilterByNick

/user/?nick={nick}

GET

User Payload

none

UserFilterByName

/user/?name={name}

GET

User Payload

none

Responses

The Task API returns three possible payloads (as JSON object arrays):

  1. Task Payload

  2. User Payload

  3. Error Payload

See below for details.

Task Payload

A Task object looks like this:

Single Task Object
{
  "task" : [
    {
      "id" : "137h96l7mpv",
      "title" : "LAX",
      "completeFlag" : "true",
      "assignedUser" : "bob",
      "dateCreated" : "2016-01-14T17:48:42.083Z",
      "dateUpdated" : "2016-01-26T03:39:08.266Z"
    }
  ]
}

Task objects MUST be returned as a named array (task). The array MAY have only one member. The valid list of properties for a Task object are: [id], [title], [completeFlag], [assignedUser], [dateCreated], and [dateUpdated]. See Data Elements for more information on each property.

User Payload

A User object looks like this:

User Object
{
  "user" : [
    {
      "id" : "alice",
      "nick" : "alice",
      "password" : "a1!c#",
      "name" : "Alice Teddington, Sr.",
      "dateCreated" : "2016-01-18T02:12:55.747Z",
      "dateUpdated" : "2016-01-18T03:26:36.572Z"
    }
  ]
}

User objects MUST be returned as a named array (user). The array MAY have only one member. The valid list of properties for a User object are: [id], [nick], [password], [name], [dateCreated], and [dateUpdated]. See Data Elements for more information on each property.

Error Payload

When the service encounters an error (HTTP 4xx or 5xx) the service returns an Error Payload that looks like this:

Error Payload
{
  "error" : {
    "code" : "404",
    "message" : "Not Found",
    "url" : "http://rwcbook02.herokuapp.com/invalid-url/"
  }
}

The first element in an Error Payload MUST be an error JSON object three properties. Those properties are: [code], [message], and [url]. See the Data Elements section for more details.

Requests

All payloads sent from the client to the server MUST be valid JSON Media Type messages. The messages SHOULD be in simple name-value dictionary format based on the INPUT arguments from the Task Operations and the User Operations tables.

For example, the User Operations table lists four arguments for the UserChangePassword operation: [nick], [oldPass], [newPass], and [checkPass]. When constructing a request body for this operation, it SHOULD look like this:

Change Password Request Body
{
  "nick" : "jt",
  "oldPass" : "p#ssW0rd",
  "newPass" : "n#wP@ss",
  "checkPass" : "n#wP@ss"
}

Data Elements

What follows is a list of all the possible data elements that MAY appear within a TPS web API payload. Note that these values can appear in both requests and responses.

Note
 This list is in alphabetical order. Note the references in each definition to learn which TPS web API payloads use each data element.

assignedUser

Indicates the user to which this record is assigned. This value of this data element MUST match an existing User [id] value. See User Payload.

checkPass

Check value to use when changing the [oldPass] to [newPass]. The value of [checkPass] MUST exactly match the value of [newPass].

code

HTTP Error code. See Error Payload.

completeFlag

Indicates the completion status of this record. Valid values for this data elements are: "true" and "false". See Task Payload.

dateCreated

The date this record was created. The value of this data element MUST in the ISO 8601 form. See Task Payload, User Payload.

dateUpdated

The date this record was last updated. The value of this data element MUST in the ISO 8601 form. See Task Payload, User Payload.

id

The record/object identifier. See Task Payload, User Payload.

message

Application-specific error description. See Error Payload.

name

Name string for this record. See User Payload.

newPass

The new password for the user account. Used to change the [oldPass] to a new value.

nick

The nickname of the user. The value of this data element SHOULD match the value of the User [id] data element. See User Payload.

oldPass

The existing password for the user account. Used to change the existing password to [newPass].

password

The password for the user account. See User Payload.

title

Title string for this record. See Task Payload.

url

URL that was invokved that caused the error. See Error Payload.

Extensions

This document describes the Tasks CRUD service. Any extensions to this service MUST not redefine or change the use/meaning of any URLs, objects (or their properties), arrays, properties, etc. defined in this document. Clients that do not recognize extensions to the service SHOULD ignore them.

Warning
 It is possible that future forward-compatible modifications to this specification will include new elements, attributes, attribute values, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions.

The details of designing and implementing compatible extensions is beyond the scope of this document.