Calling the API

As a REST API, you can create, update or delete a series of resources that reference the entities of HacknPlan, such as projects, work items, design elements, boards, stages, categories… You need to perform a call to the URL of a resource with the desired HTTP verb (GET, POST, PUT, DELETE…).

Important: The HacknPlan Public API only works with JSON format, so all your calls need to have the Content-Type: application/json header in place.

Let’s take a look at several examples.

Getting a list of resources

To retrieve a list of the projects you are part of, you need to perform a GET call to https://api.hacknplan.com/v0/projects including the Authorization and Content-Type headers.

This call will return an array of project objects in JSON format with the following structure:

[ {
    "id": 0,
    "workspaceId": 0,
    "name": "string",
    "description": "string",
    "generalInfo": "string",
    "closingDate": "2019-11-25T16:28:19.898Z",
    "creationDate": "2019-11-25T16:28:19.898Z",
    "owner": {
      "id": 0,
      "username": "string",
      "email": "string",
      "name": "string",
      "creationDate": "2019-11-25T16:28:19.898Z"
    },
    "costMetric": "string",
    "isDemo": true,
    "hoursPerDay": 0,
    "moduleConfig": {
      "workItems": true,
      "workItemCategories": true,
      "workItemDates": true,
      "workItemCosts": true,
      "workItemSubTasks": true,
      "workItemDependencies": true,
      "workItemAttachments": true,
      "workItemComments": true,
      "workItemTags": true,
      "gameDesignModel": true,
      "gameDesignModelTypes": true,
      "gameDesignModelDates": true,
      "gameDesignModelAttachments": true,
      "gameDesignModelComments": true,
      "calendar": true,
      "burndownChart": true,
      "ganttChart": true,
      "metrics": true,
      "activity": true,
      "notifications": true,
      "forceWorkItemDesignElement": true,
      "forceWorkItemBoard": true,
      "forceWorkItemEstimatedCost": true,
      "forceWorkItemDueDate": true,
      "forceWorkItemDescription": true,
      "forceWorkItemUser": true,
      "forceWorkItemTag": true
    },
    "defaultBoardId": 0
  }]

Getting a specific resource

Continuing with the examples of the GET verb, when you need to retrieve a specific resource you have to specify the unique identifier of the resource in the URL. For instance, if the id of your project is 100, you should perform a GET call to https://api.hacknplan.com/v0/projects/100.

Another example: if you want to retrieve the work item with id 25 of that same project, you would call https://api.hacknplan.com/v0/projects/100/workitems/25.

You can get a reference for all the endpoints here.

Creating a resource

Let’s imagine we want to create a new task. In order to create a new task for your project with id 100, you need to perform a POST call to https://api.hacknplan.com/v0/projects/100/workitems, including the same header than the GET calls. However, since this is the creation of a new resource, we need to add body content to the request including a JSON object with the data of our new task. The format would be something like this:

{
    "title": "string",
    "description": "string",
    "parentId": 0,
    "isStory": false,
    "categoryId": 0,
    "estimatedCost": 0,
    "importanceLevelId": 0,
    "boardId": 0,
    "designElementId": 0,
    "startDate": "2019-11-25T16:28:20.172Z",
    "dueDate": "2019-11-25T16:28:20.172Z",
    "assignedUserIds": [0],
    "tagIds": [0],
    "subTasks": ["string"],
    "dependencyIds": [0]
}

This action does not only require you to know the unique identifier of the project but also the one for all the rest of the entities that a task references, like a category, importance level, design element… If all the provided information is correct, the request will return the status code 201: Created.

You can take a look at all the details of this endpoint on our API Reference page.

Updating resources

Following the REST design conventions, the resources provided through our API can be updated using two different actions, PUT and PATCH. The difference between the two is that, while PUT requires that you update the whole entity with all its fields, the PATCH action allows you to update only the fields of the entity that are included in the body object.

For instance, let’s say we want to update the description of one of our boards with id 5. If we are using PUT, we would call https://api.hacknplan.com/v0/projects/100/boards/5 with the following body content:

{
    "name": "My board",
    "description": "My updated board description",
    "generalInfo": "My general information in Markdown",
    "startDate": "2019-11-01T16:28:19.713Z",
    "dueDate": "2019-11-25T16:28:19.713Z",
    "milestoneId": null
}

In this case, all editable board fields need to be included in the call payload, and the ones which are optional and not included are set to null. If there are mandatory fields that are not included, the call would throw a formatting error. All the fields are replaced and stored.

However, if we used PATCH instead, we would do the same call to https://api.hacknplan.com/v0/projects/100/boards/5, but the payload would be:

{
    "description": "My updated board description"
}

In this case, only the description field would be updated, while the rest would remain untouched.

It is important to notice that in case you want to set a field to null, you need to use PUT because PATCH would treat that null as if the field was not included, hence it wouldn’t be modified at all.

Deleting a resource

Removing a resource only requires performing a call to the resource URL using the DELETE verb. For instance, deleting a work item with id 25 would require you to call DELETE to https://api.hacknplan.com/v0/projects/100/workitems/25, and a 200 OK response would be returned if the item was successfully deleted.

Knowledge Base