Designing a REST API that works well with Tasktop is challenging. There are a lot of subtle things that can go wrong during the API design phase that can make it difficult for Tasktop to flow data to and from an ALM system.
A first-class entity is an object that the API allows you to directly manipulate. Let’s consider the case where your ALM system has two first-class entities: Tickets and Users. Tickets are the items that represent a unit of work that needs to be done. Users are the people involved in doing the work such as software developers, managers, and QA testers.
First-class entities
Every first-class entity in your system needs to have a stable and unique identifier. For a work item such as a Ticket, the ID could be a number or a UUID. For a User, the ID is often the username or the email address.
The API documentation should be clear about what the first-class entities are, how they are referenced, and what data they carry with them.
The ID of an entity allows us to uniquely identify it and it must be guaranteed to not change during the lifetime of the entity. The summary is often a human-readable description of that particular entity. Created and modified dates are useful for being able to query on issues that pertain to a particular time period. The ‘version’ property allows Tasktop to tell whether or not the entity has been changed since the last time that it has been seen.
Work Items
A Ticket in your system may be represented like this:
{
“id”: 12401,
“summary”: “Update the website”,
“description”: “We <b>need</b> to update the website”,
“assignee”: “rsantinon”,
“status”: “OPEN”,
“created”: “2017-04-28T19:10:22.0070000Z”,
“modified”: “2018-02-12T11:15:22.0070000Z”,
“version”: 1
}Tasktop also requires an abstract definition of the object model which specifies what the data type and constraints of each field are. For example, the API call:
GET /api/tickets/metadata
Might return a JSON object like this:
{“fields”: [
“id”: {“type”: “number”, “readonly”: true},
“summary”: {“type”: “text”, “readonly”: false},
“description”: {“type”: “html”, “readonly”: false},
“assignee”: {“type”: “user”: “readonly”: false},
“status”: {“type”: “select”, “readonly”, false},
“created”: {“type”: “datetime”, “readonly”: true},
“modified”: {“type”: “datetime”, “readonly”: true},
“version”: {“type”: “number”, “readonly”: true}
]
}This field schema states what the data type is and whether or not the field is read-only. In this example, users of the API are allowed to change the summary, description, assignee and the status but not the other fields. Tasktop will use this data to determine that, for example, it makes sense to synchronize another user into the ‘assignee’ field, but it doesn’t make sense to synchronize a date into the ‘created’ field.
In this example, the only constraints on a field are whether it is read-only or not but in a real ALM system there are a variety of different types of constraints:
- Requiredness: whether or not a field is required to be set upon creating a ticket. Often the summary and status fields are required, but a description is not.
- Data ranges: date fields may only accept dates within a certain range and number fields often only accept numbers represented by a certain number of digits
- Character restrictions: which special characters are allowed in which fields.
- Relative date restrictions: If a ticket has both ‘planned start’ and ‘planned end’ date fields, then it makes sense that the end must be a later date than the start.
It is important to provide field constraint information either through the API (as in the metadata call above) or in the documentation. Developers integrating with your product don’t want to have to use trial and error to determine which values can go into each field. If your ALM system allows users to create custom fields, then it is necessary to provide the custom field metadata through the API so that Tasktop can integrate with it.
Users
The object representing ALM users are usually quite simple. Tasktop requires the user API to provide only a unique identifier. Usually user objects also contain a display name too.
Requesting a user object might return something like this:
{
“username”: “rsantinon”,
“name”: “Rylan Santinon”,
“email”: “[email protected]”,
“active”: true
}The schema of this object is pretty self-explanatory. It contains the ‘username’ as the unique identifier and the name, email address and an active flag.
The ‘active’ flag is a feature that that allows “soft deletion” of users which solves the problem of what to do with users who have left the company. Deleting the user causes problems because then you would have work items that reference an object that doesn’t exist in the system.
Tasktop can use the users’ name and email address in order to automatically match users in two different ALM systems.
We love talking about designing APIs and value stream integration, chat to us today about any questions you have!
