Integrating the zipBoard API into User Application
Overview
This document describes the steps required to integrate the zipBoard API into the user application.
Following the steps will let the user application connect to the API, create Projects, insert files(URL) into zipBoard and sync the comments between zipBoard and the app.
Typographic Convention
| Convention | Description |
Click Edit Profile |
The word in box indicates a clickable object |
| Locate the API Key section | The italicized word indicates a section in the webpage |
| *title: project name | The *asterisk indicates required field |
| The user must have one of ... | The underlined sentence indicates a requirement for the function |
| |
Authentication
zipBoard uses HTTP token authentication for its API, and to get/refresh the token:
1. Log in to zipBoard and click on the User Icon in the top right corner
2. Click Edit Profile
3. Locate the API Key section in the lower portion of the page
4. Click on the ➕/🔄 to generate/refresh the API key
5. Highlight and copy the API Key and insert it into the code for authentication
For more information on Authentication, please check the API Authentication and URI Structure.
Adding projects
| Action | Endpoint URI | Function |
| Create Project | POST https://app.zipboard.co/api/v1/projects | Creates a new project for the user and returns the project data of the newly created project. |
Data Inputs
The data type for the inputs is String, unless indicated otherwise.
Header:
| Content-Type | ‘application/json’ |
| Authorization | Authorization token from Authentication |
Body:
| *title | The name of the project |
| orgid | The id of Organization in which the project should be made in |
| description | The Description for the project |
| projectid | Custom project Id for the project |
On completion, The request will return status code 201, along with the project data, which includes the project id of the newly created project. For more information, please check the API for Project.
Adding Files (URL)
The user must have one of the following roles to add files: [Owner, Manager, reviewer, Project Owner]
| Action | Endpoint URI | Function |
| Create Files | POST https://app.zipboard.co/api/v1/files/ | Creates a new file in the project specified. |
Data Inputs
The data type for the inputs is String, unless indicated otherwise.
Header:
| Content-Type | ‘application/json’ |
| Authorization | Authorization token from Authentication |
Body:
| *name | The name of the file |
| *projectid | The id of the project in which the file should be created in |
| *url | The URL of the file |
| description | description of the file |
On completion, the request will return an object with message: “File successfully created” along with the file Id, reviewURL and other data. For more information, please check API for FIles (URL).
Syncing comments (task)
From User Application to zipBoard
The user must have one of the following role to add/update tasks: [Owner, Manager, reviewer]
| Action | Endpoint URI | Function |
| Create Task | POST https://app.zipboard.co/api/v1/issues/tasks/ | Creates a new task in zipBoard |
| Update Task | PUT https://app.zipboard.co/api/v1/issues/tasks/:id | Update the specified task in zipBoard |
Creating new Tasks
Data Inputs
The data type for the inputs is String, unless indicated otherwise.
Header:
| Content-Type | ‘application/json’ |
| Authorization | Authorization token from Authentication |
Body:
| *title | The title of the task |
| *projectid | The id of the project in which the task should be created in |
| type | One of the 4 types of the task: ‘Bug’, ‘Enhancement’, ‘Feature’, ‘Task’ |
| priority | One of the 4 priority levels: ‘Low’, ‘Medium’. ‘High’, ‘Critical’ |
| status | The task status name found in zipBoard (default status if left empty) |
| file_id | The Id of the file in which the task originates from |
| description | description of the file |
On completion, the request will return status code 201 along with the new task data.
Updating Existing Tasks
Data Inputs
The data type for the inputs is String, unless indicated otherwise.
Header:
| Content-Type | ‘application/json’ |
| Authorization | Authorization token from Authentication |
URL Params:
| *id | id of the task to be updated |
Body:
At least one is required from optional Body parameters.
| title | The title of the task |
| type | One of the 4 types of the task: ‘Bug’, ‘Enhancement’, ‘Feature’, ‘Task’ |
| priority | One of the 4 priority levels: ‘Low’, ‘Medium’. ‘High’, ‘Critical’ |
| status | The task status name found in zipBoard (default status if left empty) |
| description | description of the file |
On completion, the request will return status code 200 along with the updated task data.
From zipBoard to User Application
the user must be logged in and authenticated in order to view tasks
| Action | Endpoint URI | Function |
| Get Task | GET https://app.zipboard.co/api/v1/issues/tasks/ | Get the list of tasks that satisfies the condition specified. |
Data Inputs
The data type for the inputs is String, unless indicated otherwise.
Header:
| Content-Type | ‘application/json’ |
| Authorization | Authorization token from Authentication |
URL Params:
| id | id of the task to fetch |
Body:
fileid or/and projectid is required
| projectid | The project to fetch the list of tasks |
| fileid | The file to fetch the list of tasks |
| priority | One of the 4 priority levels: ‘Low’, ‘Medium’. ‘High’, ‘Critical’ |
| status | The task status name found in zipBoard (default status if left empty) |
| type | One of the 4 types of the task: ‘Bug’, ‘Enhancement’, ‘Feature’, ‘Task |
On completion, the request will return status code 200 along with data (array), which can be used to update/add comments in the user application. For more information, please check API for Issues (Task).
To find out more about the features of zipBoard API, please visit the zipBoard API Documentation page.