Requests and Responses

General RESTful API Resources and Methods

For background on RESTful APIs in general, see Wikipedia or another suitable reference.

HTTP Methods

If you want to

Then you should

fetch all instances of a resource

GET /api/v1/resource

fetch a single instance of the resource

GET /api/v1/resource/:id

create a new resource

POST /api/v1/resource

update an existing resource

PUT /api/v1/resource/:id

delete an existing resource

DELETE /api/v1/resource/:id

If your HTTP client does not implement the PUT and DELETE methods, then you can use a POST with an additional parameter named _method and a value of either PUT or DELETE.

For example, to delete a task using the POST method rather than the DELETE method, do:

% curl https://app.liquidplanner.com/api/workspaces/:id/tasks/:id?_method=DELETE -X POST

HTTP Status Codes

Check the HTTP status code of responses from the API to determine whether your request was processed successfully.

Success Codes

Status Code

Result

200 OK

successful read, update, or delete

201 Created

successful create

Error or Exception Codes

Status Code

Result

400 Bad Request

unrecognized or invalid request URL

401 Unauthorized

credentials not provided or are incorrect

422 Unprocessable Entity

unsuccessful create, update, or delete; syntactic or validation error

404 Not Found

record does not exist, or you do not have permission to access it

500 Internal Server Error

unexpected error; you've likely found a bug in LiquidPlanner

501 Not Implemented

you asked for an API version that is not implemented (either because it does not exist, or it has been deprecated)

503 Service Unavailable

API is disabled globally, or your account is throttled; check the error in the response body

Error Responses

Response Body

When returning an error, the response body contains details of the error represented as a JSON hash.

For example, requesting an invalid task id results in the following error response:

% curl https://app.liquidplanner.com/api/workspaces/12345/tasks/12345
{
  "type": "Error",
  "error": "NotFound",
  "message": "Record not found (or you don't have permission to access it)."
} 
 Status: 404 Not Found

Hash Keys of an Error Response

Key

Description

type

the literal string "Error"

error

specific kind of error, e.g. "NotFound" or "BadRequest"

message

descriptive or explanatory message

Writing via the API

Many, but not all, resources can be created or modified via the API. As a general rule, things that you can create or edit inside the “Projects” tab in the Web UI (tasks, projects, documents, comments, etc.) are also writable via the API.

On the other hand, administrative resources (members, workspace settings, activities, etc.) are in general not writable via the API.

When creating or modifying a resource, the payload should always be a JSON hash with a single root attribute: the lower-case name of the resource you are writing (except when dealing with the convenience methods, specified below). The value of that attribute should be a hash of all the attributes you’d like to write.

Create an item using POST, and update an item using PUT.

Resource Parameter

When creating or updating a resource, the API requires a request parameter with the same name as the resource (in the singular form), whose value is a hash of the resource’s attributes.

Putting together the HTTP methods, resource nesting, and the resource parameter, we have the following:

If you want to

Then you should

To

With a parameter

Create a Task

POST

/api/v1/workspaces/:workspace_id/tasks

task = ...hash

Create a Comment on a Task

POST

/api/v1/workspaces/:workspace_id/tasks/:task_id/comments

comment = ...hash

Update a Folder

PUT

/api/v1/workspaces/:workspace_id/folders/:folder_id

folder = ...hash

You can reference the available resources at: https://app.liquidplanner.com/api/v1/help/urls