API Description

Request Structure

The awork API is available via HTTPS endpoints and follows a RESTful address structure where resources are selected with text and Id segments in the URL. Typically Ids are in Guid format, i.e. a hexadecimal representation of a 128-bit integer separated by hyphens.
Other values are usually sent in the body of the request, which are only accepted in JSON format (content type: application/json).

The URL of our API is composed of three different segments:

• The base URL: https://api.awork.io/api/v1
• The content/resource url: /users
• The filter query (optional):?page=1&pageSize=50

The complete URL can look like this: https://api.awork.io/api/v1/users?page=1&pageSize=50

CRUD Calls vs. Business Operations

Most API calls contain simple CRUD endpoints to handle the data manipulation for that particular entity. In some cases the default POST, PUT or DELETE routes are replaced by so-called business operations. The reason for this separation is that actions do not only manipulation the entity itself, but also affect other entities or even trigger further actions, workflows or events in other parts in awork. An example for this would be an automatic task creation triggered by the status change of a project.

Business operations can be identified by an additional segment in the URL, which usually begins with a verb. For Example:

• setArchived
• removeProjectMember
• renameTag
• setStatus
• etc.

Deleted vs. Archived

In some cases, deleting an object can have unintended side effects because of dependencies of other objects. An example for this is the project type. Once you’ve linked projects to a particular type, it can be complicated to delete the type because you will have to move all projects using that type to another type. For these cases you can set that particular object to archived, which is a form of soft-deletion. Once flagged as archived, it can no longer be used, but still exists for legacy data it is already linked to.

Error Handling

In case a request to our API fails, the return value of the endpoints follows standard HTTP status code conventions. A detailed reason can be found in the response. Common codes indicating a client error are 400 (Bad Request) & 404 (Not Found). To give some further information on the cause of the error the API also returns a standardized error object in the response body:

• Code: These string error-codes are constants indicating the exact misbehaviour. The following codes are in use:

• Description: A human-readable explanation for the cause of the error.
  For example:
  • Identity cannot be invited to this team. The identity is already part of the team.
  • The password is too simple
• Space: An interesting fact about space.
• Link: A link to the corresponding documentation.
• Details: Further explanations or hints on fixing the request.
• ValidationErrors: If the model validation failed, all violations are listed here.

HTTP Status Codes

On each request to our API you get a response with a HTTP status code that indicates if it was successful.

Success Status Codes

GET           200 (OK) including the object(s)
POST          200 (OK) including the newly created object
              202 (Accepted) for batch or background operations
              204 (No content) for business operations without a return value
PUT           200 (OK) including the updated object
DELETE        204 (No content)

400 (Bad request)   When the request model is invalid or the operation is not allowed
401 (Unauthorized)  When the requesting user is lacking the necessary permissions for the request
404 (Not found)     When a requested resource does not exist

Pagination

How to find the total number of results?

When you make a call to retrieve the users from the API, you get the response as well as its headers. The headers of the response contain a property named “aw-totalitems”, which provides the information about the maximum retrievable results.

Any smart options?

You can sort as well as filter the data that you would like to get from the API by specifying the properties sortby and order.

Filter

The API uses a subset of the query syntax from ODATA, so most of the common queries will be compatible.

Tags

Tags are small strings of additional information that can be added to certain entities. Tags are simple strings with no additional data, but they help to categorize the entities and it is easier to find them via uplink.