UpStream has powerful developer features, which can be accessed using the UpStream API module. In this document, we will explain how to use the API.
UpStream expands the standard API functionality built into WordPress. So we recommend that you familiarize yourself with the WordPress API before trying to use the UpStream API functionality.
For more information on the WordPress API, including how to use it, see this.
Getting Started with UpStream API
This section explains how to get up and running with the UpStream API with WordPress. If you’re comfortable with the WordPress API, you can skip this section.
The first thing you need to do in order to use the UpStream API is to install an authentication plugin.
Although you shouldn’t use it for production, for a test installation, the easiest authentication plugin to use is the JSON Basic Authentication plugin. You can download it from Github. Once you have downloaded, installed, and activated it, you can start developing with the API.
For this article, we will be using the Talend API Tester Google Chrome addon, which you can get from the Chrome App Store.
Authentication
Authentication into the UpStream API is purely based on the authenticated WordPress REST API user.
If you have the JSON Basic Authentication plugin enabled, you will need to pass an Authorization header with the username and password of the user you are logging in as.
Note that in order to be able to use the UpStream API, you must be logged into the WordPress REST API as a user with manage_upstream permissions. That means that any user who has access to the UpStream API can manipulate any object, regardless of owner or client.
UpStream Objects
The UpStream API allows access to the following object types:
| Object | Operations | Object URL Component |
| Project | GET, POST, PUT | projects |
| Milestone | GET, POST, PUT | milestones |
| Task | GET, POST, PUT | tasks |
| Bug | GET, POST, PUT | bugs |
| File | GET, POST, PUT | files |
| Client | GET, POST, PUT | clients |
Queries to the API are of the form
https://<yourserver>/wp-json/upstream/v1/<object-url-component>For example:
https://my-wordpress-server/wp-json/upstream/v1/projects?id=1UpStream API GET
Now, we will start with the queries. To get any object by ID, you can use an HTTP GET query. The ID is passed as a query parameter. For any GET queries, you must pass the fields you want as an array of field[] parameters.
Here is an example:
https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=descriptionAnd here is the query above run:
And here is the result:
{"title":"Drawing App","description":""}When you are querying projects, clients, or milestones, you can use the form above.
When you are querying tasks, files, and bugs, you must pass in the project ID as project_id in the request as well. For example,
https://my-wordpress-server/wp-json/upstream/v1/tasks?id=15ed2d17f52485&fields[]=title&project_id=165Will return:
{"title":"Design Interface"}The fields options are below:
Project Fields
| Field | Description | Notes |
| title | The title of the project. | |
| description | The description of the project. | |
| status | The status of the project. | Returns the status text. |
| categories | The categories of this project. | Returns a JSON array of WordPress term objects. |
| assignedTo | The WordPress user ID of the owner of the project. | Returned as a one element array for compatibility. |
| startDate | The start date of the project. | Date formatted as |
| endDate | The end date of the project. | Date formatted as YYYY-MM-DD |
| clientId | The client ID of the client that this project is attached to. | |
| clientUserIds | The user IDs of the client users attached to this project. | |
| elapsedTime | The total elapsed time in hours for the project. | Only available if the Time Tracking module is enabled. |
Task Fields
| Field | Description | Notes |
| title | The title of the task. | |
| notes | The notes for the task. | |
| status | The status of the task. | Returns the status text. |
| assignedTo | The WordPress user IDs of the owners. | |
| milestoneId | The ID of the milestone this task is attached to. | |
| startDate | The start date of the task. | Date formatted as YYYY-MM-DD |
| endDate | The end date of the task. | Date formatted as YYYY-MM-DD |
| progress | The numerical progress percentage. | |
| elapsedTime | The total elapsed time in hours for the project. | Only available if the Time Tracking module is enabled. |
Milestone Fields
| Field | Description | Notes |
| title | The title of the milestone. | |
| notes | The notes for the milestone. | |
| color | The color of the milestone. | |
| progress | The progress % of the milestone. | |
| categories | The categories of this milestone. | Returns a JSON array of WordPress term objects. |
| assignedTo | The WordPress user IDs of the owners of the milestone. | |
| startDate | The start date of the milestone. | Date formatted as m/d/Y |
| endDate | The end date of the milestone. | Date formatted as m/d/Y |
File Fields
| Field | Description | Notes |
| title | The title of the file. | |
| description | The description of the file. | |
| assignedTo | The WordPress user IDs of the owners of the file. | |
| fileId | The WordPress media ID of the file. | Not compatible with private files. |
Bug Fields
| Field | Description | Notes |
| title | The title of the bug. | |
| description | The description of the bug. | |
| dueDate | The due date of the bug. | Date formatted as YYYY-MM-DD |
| severity | The severity of the bug. | |
| status | The status of the bug. | |
| assignedTo | The WordPress user ID of the owner of the bug. | |
| fileId | The WordPress media ID of the attached file. | Not compatible with private files. |
Client Fields
| Field | Description | Notes |
| title | The name of the client. | |
| phone | The phone number for the client. | |
| website | The website for the client. | |
| address | The address of the client. | |
| userIds | The user IDs of all of the users connected to this client. | Returned as an array |
Querying All Items
You can query all projects by performing a GET to the projects endpoint. Note, for all of the following you must still pass the fields that you want returned in the query:
https://<yourserver>/wp-json/upstream/v1/projects?fields[]=<title>You can query all projects for a certain client by performing a GET to the projects endpoint and passing the client_id in the request:
https://<yourserver>/wp-json/upstream/v1/projects?client_id=<client ID>&fields[]=<title>You can query all clients performing a GET to the clients endpoint:
https://<yourserver>/wp-json/upstream/v1/clients?fields[]=<title>You can query all milestones, fields, tasks, files, and bugs for a project by querying the corresponding endpoint and passing the project_id in the request:
https://<yourserver>/wp-json/upstream/v1/tasks?project_id=<project ID>&fields[]=<title>
https://<yourserver>/wp-json/upstream/v1/milestones?project_id=<project ID>&fields[]=<ID>
https://<yourserver>/wp-json/upstream/v1/bugs?project_id=<project ID>&fields[]=<status>UpStream API POST
You can create an object by doing an HTTP POST to the object URL. When doing this, you must pass the creator user ID in the query string. In addition, in the JSON body of the POST, you must pass the fields that you want to set.
For example, you can create a project by POSTing to the following type of URL:
https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID>You will need to POST a JSON object with the fields that you want to set, but at the minimum, you must pass a title, like this:
{
"title": "my project"
}For tasks, files, and bugs you must pass in the project ID in the GET URL, like this:
https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID>&project_id=<project ID>You must pass a JSON object in the POST body, with at least the title field filled in. You can pass any other fields as well.
For a full list of fields, with rules and parameters, see the PUT section below.
UpStream API PUT
To modify an object, you can do an HTTP PUT to the object URL. The URL structure is similar to above. For instance, to change a project field, you do a PUT request to:
https://<yourserver>/wp-json/upstream/v1/projects?id=<project ID>In the PUT body, you pass a JSON object with the field data, in the form above.
For tasks, files, and bugs you must pass in the project ID in the GET URL, like this:
https://<yourserver>/wp-json/upstream/v1/tasks?id=<task ID>&project_id=<project ID>You can set individual fields, or you can set multiple fields at the same time. Below is a list of all possible fields and their parameters:
Project Fields
| Field | Description | Data Type |
| title | The title of the project. | String |
| description | The description of the project. | String |
| status | The status of the project. | String – must match the name of a status option |
| categoryIds | The IDs of the categories of this project. | Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘project_category’ |
| assignedTo | The WordPress user ID of the owner of the project. | Single element array |
| startDate | The start date of the project. | Date formatted as YYYY-MM-DD |
| endDate | The end date of the project. | Date formatted as YYYY-MM-DD |
| clientId | The client ID of the client to attach this project to. | Integer — must be a valid client ID. |
| clientUserIds | The list of user IDs from the client that are attached to this project. | An array of user IDs that are already attached to the client. |
Task Fields
| Field | Description | Data Type |
| title | The title of the task. | String |
| notes | The notes for the task. | String |
| status | The status of the task. | String – must match the name of a status option |
| assignedTo | The WordPress user IDs of the people assigned to the task. | WordPress user ID |
| milestoneId | The ID of the milestone this task is attached to. | Integer milestone ID |
| startDate | The start date of the task. | Date formatted as YYYY-MM-DD |
| endDate | The end date of the task. | Date formatted as YYYY-MM-DD |
| progress | The numerical progress percentage. | Integer – UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …) |
Milestone Fields
| Field | Description | Data Type |
| title | The title of the milestone. | String |
| notes | The notes for the milestone. | String |
| color | The color of the milestone. | String – HTML color code |
| categoryIds | The category IDs of the milestone. | Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘upst_milestone_category’ |
| assignedTo | The WordPress user IDs of the people assigned to the milestone. | WordPress user ID |
| startDate | The start date of the milestone. | Date formatted as YYYY-MM-DD |
| endDate | The end date of the milestone. | Date formatted as YYYY-MM-DD |
File Fields
| Field | Description | Data Type |
| title | The title of the file. | String |
| description | The description of the file. | String |
| assignedTo | The WordPress user IDs of the people assigned to the file. | WordPress user ID |
| fileId | The WordPress media ID of the file. You will need to upload the file separately. | Private files are not supported by the API |
Bug Fields
| Field | Description | Data Type |
| title | The title of the bug. | String |
| description | The description of the bug. | String |
| dueDate | The due date of the bug. | Date formatted as YYYY-MM-DD |
| severity | The severity of the bug. | String – must match the name of a severity option |
| status | The status of the bug. | String – must match the name of a status option |
| assignedTo | The WordPress user IDs of the people assigned to the bug. | WordPress user ID |
| fileId | The WordPress media ID of the attached file. You will need to upload the file separately. | Private files are not supported by the API |
Client Fields
| Field | Description | Notes |
| title | The name of the client. | |
| phone | The phone number for the client. | |
| website | The website for the client. | |
| address | The address of the client. | |
| userIds | The user IDs of all of the users connected to this client. | Passed as an array of IDs. If a user is already added, the user will be ignored. NOTE: This will not currently remove users from a client. |
Examples
Here are some examples of the API. You will find more examples in the examples/rest_examples.php file in the API module.
Get Project Title and Status
Request:
GET https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=statusResponse:
{
"title": "Drawing App",
"status": "In Progress"
}Set Project End Date and Status
Request:
PUT https://my-wordpress-server/wp-json/upstream/v1/projects?id=165Request body:
{"endDate":"2021-01-01","status":"In Progress"}Result:
Create a Task in a Project
Request:
POST https://my-wordpress-server/wp-json/upstream/v1/tasks?project_id=165&creator_id=1Request body:
{"title":"My New Task","notes":"This is a new task created by the API."}Response body:
{
"id": "15ef602687fe8e"
}Result:
Deleting Objects
Deleting objects is not currently permitted. To avoid issues, you must delete objects from the interface.
Using the API Locally
UpStream has an easy-to-use local API and object model, which allows you to do nearly anything you can do with the interface, such as creating, editing, and updating tasks, projects, clients, bugs, and time records.
The UpStream API module comes with a file under the examples/ folder named local_examples.php. That file contains examples of how to perform most operations using the local UpStream API.