2. 2
CONTENT
INTRODUCTION ...................................................................................................................................... 4
HOW TO USE SCRUMDESK API ................................................................................................................ 4
USAGE SCENARIOS ................................................................................................................................. 4
1. AUTHENTICATION ................................................................................................................................ 5
BASIC AUTHENTICATION ........................................................................................................................................... 5
2. ACCESSING PROJECTS ............................................................................................................................ 5
ALL PROJECTS ......................................................................................................................................................... 5
PROJECT DETAILS .................................................................................................................................................... 5
3. RELEASES ........................................................................................................................................... 5
RELEASES OF A PROJECT ........................................................................................................................................... 5
RELEASE DETAILS ..................................................................................................................................................... 5
4. SPRINTS ............................................................................................................................................. 5
ALL SPRINTS OF A PROJECT........................................................................................................................................ 5
SPRINT DETAILS....................................................................................................................................................... 6
5. STORIES ............................................................................................................................................. 6
STORIES OF A PROJECT ............................................................................................................................................. 6
STORIES OF A SPRINT ............................................................................................................................................... 6
STORIES OF A RELEASE.............................................................................................................................................. 6
STORIES ASSIGNED TO AN USER ................................................................................................................................. 6
STORIES OF A PROJECT ORDERED BY SELECTED ATTRIBUTES ............................................................................................. 6
SELECTION OF THE FIRST N STORIES OF A PROJECT ........................................................................................................ 6
SELECTION OF ANY N STORIES OF A PROJECT ................................................................................................................ 6
STORY DETAILS ....................................................................................................................................................... 7
6. TASKS ............................................................................................................................................... 7
TASKS OF A STORY ................................................................................................................................................... 7
TASK DETAILS ......................................................................................................................................................... 7
7. TEAM MEMBERS .................................................................................................................................. 7
GET TEAM MEMBERS ............................................................................................................................................... 7
TEAM MEMBER DETAILS ........................................................................................................................................... 7
8. CREATE A NEW ENTITY ........................................................................................................................... 7
UPDATE AN ENTITY ................................................................................................................................ 8
MERGE-BASED UPDATE ............................................................................................................................................ 8
REPLACE-BASED UPDATE .......................................................................................................................................... 9
DELETE AN ENTITY .................................................................................................................................. 9
4. 4
Introduction
ScrumDesk API allows to easily integrate 3rd party systems and applications with ScrumDesk.
API allows managing agile projects and working with data representing projects, stories, tasks etc.
ScrumDesk API is a service provided by ScrumDesk s.r.o. company to access hosted data. It is also possible
to install it in local environment and connect it with data stored in the company environment.
How to use ScrumDesk API
The ScrumDesk API is a platform as a service. All information are provided by web data service. To learn
how to create client application using .NET see Microsoft guidelines.
To get or update your project(s) you need to make an HTTP request with data. The response is provided as
JSON or XML data form. Different API calls use different HTTP verbs like GET, POST, PUT and DELETE. If you
want to send request or receive response in JSON format you must add Accept:application/json tag into
http header or you can use $format=json parameter in URL.
Every request to ScrumDesk API starts with base URL so we will use relative URL in examples below. If you
use ScrumDesk API installed on our server (hosting.scrumdesk.com) the base url is
http://hosting.scrumdesk.com:81/WebAPI/ScrumDesk.svc. If you use your installation of ScrumDesk API
the base url is http://address_of_your_server:port_number/WebAPI/ScrumDesk.svc
Usage scenarios
Following paragraphs will guide you through a simple usage how to get and work with data accessible by
ScrumDesk API.
Our example describes basic steps covering typical workflow in which your application can call API to
provide fundamental functionality of scrum project management tool.
Authenticate
Projects
Project
Team members
Stories
Story details
Tasks
5. 5
1. Authentication
Basic authentication
Basic authentication verifies user against ScrumDesk database and caches authenticated user in server
cache. You need to specify repository (database) as part of user login name.
Example: User authentication
Database name: ScrumDeskDatabaseName
User name: ScrumDeskUserName
Login: ScrumDeskDatabaseNameScrumDeskUserName
2. Accessing projects
All projects
List all projects stored in a customer database
{BaseURL}/Project
Project details
Get details of particular project. Project Id can be recognized by call of Get all projects
{BaseURL}/Project(projectID)
3. Releases
Releases of a project
List all releases of particular project
{BaseURL}//Project(projectID)/Release
Release details
List attributes of particular release
{BaseURL}//Project(projectID)/Release(releaseID)
4. Sprints
All sprints of a project
List all sprints of particular project
6. 6
{BaseURL}//Project(projectID)/Sprint
Sprint details
List attributes of particular sprint
{BaseURL}//Project(projectID)/Sprint(sprintID)
5. Stories
Stories of a project
List all stories in backlog of a project
{BaseURL}//Project(projectID)/Task?$filter=ParentTaskId eq null
Stories of a sprint
List all stories that belong to particular sprint
{BaseURL}/Project(projectID)/Sprint(sprintID)/Task?$filter=ParentTaskId eq null
or
{BaseURL}//Project(projectID)/Task?$filter=SprintId eq sprintID and ParentTaskId eq null
Stories of a release
List all stories that belong to particular release
{BaseURL}//Project(projectID)/Release(releaseID)/Task?$filter=ParentTaskId eq null
or
{BaseURL}//Project(projectID)/Task?$filter=ReleaseId eq releaseID and ParentTaskId eq null
Stories assigned to an user
List all stories that are assigned to particular user
{BaseURL}//Project(projectID)/Task?$filter=User/Id eq userID and ParentTaskId eq null
Stories of a project ordered by selected attributes
List all stories in backlog of a project ordered by Importance and Subject
{BaseURL}//Project([projectID)/Task?$orderby=Importance,Subject&$filter=ParentTaskId eq null
Selection of the first N stories of a project
List first n stories in backlog of a project, n is number of stories to be displayed
{BaseURL}//Project([projectID)/Task?$filter=ParentTaskId eq null$top=n
Selection of any N stories of a project
List any n stories in backlog of a project, n is number of stories to be displayed, m is number of stories to be
skipped
{BaseURL}//Project([projectID)/Task?$filter=ParentTaskId eq null&$skip=m&$top=n
7. 7
Story details
List attributes of particular story
{BaseURL}//Project(projectID)/Task(taskID)
6. Tasks
Tasks of a story
List all tasks that belong to particular story
{BaseURL}//Project(projectID)/Task(storyID)/Task1
Task details
List attributes of particular task
{BaseURL}//Project(projectID)/Task(storyID)/Task1(taskID)
7. Team members
Get team members
Team members are allowed to access project’s data. This API method allows to get the list of all team
members of a project.
{BaseURL}/Project(projectID)/ProjectUsers
Team member details
List attributes of particular team member. The ID of team member can be recognized using Get project
team members call.
{BaseURL}/Project(projectID)/ProjectUsers(projectUserID)
ProjectUser has only attributes that are related to the project (role). If you need additional attributes (e.g.
FirstName, LastName,...) you need to get attributes by following example (entity User):
List details of an user
{BaseURL}//Project(projectID)/ProjectUsers(projectUserID)/User
There is a possibility to get all information about team member at once. To get all details of an user
including team member details call:
{BaseURL}/Project(projectID)/ProjectUsers(projectUserID)?$expand=User
8. Create a new entity
To create a new entity (data), an HTTP POST request needs to be sent to the URI that points to the
container for that entity.
For example to create a new Release object you would send an HTTP POST request to the /Release URI
container (e.g. /Project(projectID)/Release).
The payload of the HTTP POST request is the entity data, encoded in any of the supported formats. The
“Content-Type” header in the HTTP request needs to indicate the format so the data service knows how to
interpret the data appropriately. Not all the properties of a given entity type need to be included; those
not included will take their default value in the server. If a given property is not nullable the create
operation will fail.
8. 8
After processing the POST request, the data service will return the entity that was created, with all of its
values updated to reflect any changes that happened on the server, such as server-generated keys,
properties modified at the database level using triggers, etc.
Example 1 – Add a new release
HTTP request: POST
URL: {BaseURL}/Project(projectID)/Release
Request headers:
accept: application/atom+xml
content-type: application/atom+xml
Request body:
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<content type="application/xml">
<m:properties>
<d:Name>New Release</d:Name>
<d:Description>New Descr</d:Description>
<d:IsArchived m:type="Edm.Boolean">false</d:IsArchived>
</m:properties>
</content>
</entry>
Update an entity
There are two possible options for updating existing entities:
a merge-based update
a replace-based update
Merge-based update
An existing entity can be modified by sending an HTTP MERGE request to the URI where the entity is
located. For example, to modify the Release entity with key ‘75’ you would use the /Release(75) URI (e.g.
/Project(projectID)/Release(75)).
In the case of merge-based updates, the payload needs to be an entity and only needs to contain the
properties that are being modified. If a property is not included, the value that is currently present in the
server will be preserved. The response from an HTTP PUT request is a 204 (No Content) HTTP response.
9. 9
Example 2 – Update release (using merge-based update):
HTTP request: MERGE
URL: {BaseURL}/Project(projectID)/Release(75)
Request headers:
accept: application/atom+xml
content-type: application/atom+xml
Request body:
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<content type="application/xml">
<m:properties>
<d:Name>New Release</d:Name>
<d:Description>New Description</d:Description>
<d:IsArchived m:type="Edm.Boolean">true</d:IsArchived>
</m:properties>
</content>
</entry>
Replace-based update
An existing entity can be modified (updated) by sending an HTTP PUT request to the URL where the entity is
located. To modify the Release entity with key ‘75’ you would use the /Release(75) URI (e.g.
/Project(projectID)/Release(75)).
In the case of replace-based updates, the payload needs to be an entity and should contain all the
properties of the entity (not including navigation properties). If a property is not included, the value is reset
on the server to the default value for the property.
Delete an entity
Entities are deleted by executing an HTTP DELETE request against the URL that identifies the entity in the
data service. No payload is necessary for a delete operation.
To delete the Release entity with key ‘75’ you would use the /Release(75) URI (e.g.
/Project(projectID)/Release(75)).
The data service response will not contain a payload. If the entity was deleted successfully then the
request will be answered as success (HTTP status 204 (No Content)), without further details.
Example 3:
HTTP request: DELETE
URL: {BaseURL}/Project(projectID)/Release(75)
10. 10
Appendix
Table 1: Query string options
Option Description Example
expand The ‘expand’ option allows you to embed one or --a project user with related user attributes
more sets of related entities in the results. /ProjectUsers(1)?$expand=User
For example, if you want to display a project user --a project user with related user and task
and user attributes, you could execute two information related to this user
requests, one for /ProjectUsers(1) and one for /ProjectUser(1)?$expand=User/Task
/ProjectUsers(1)/User.
--Project with related releases information
The ‘expand’ option on the other hand allows you and related sprints information
to return the related entities in-line with the /Project(1)?$expand=Release,Sprint
response of the parent in a single HTTP request.
You may specify multiple navigation properties to
expand by separating them with commas, and you
may traverse more than one relationship by using
a dot to jump to the next navigation property.
orderby Sort the results by the criteria given in this value. /Project?$orderby=Name
Multiple properties can be indicated by separating /Project?$orderby=Name desc
them with a comma.
/Project?$orderby=Name desc, Description
The sort order can be controlled by using the “asc” asc
(default) and “desc” modifiers.
skip Skip the number of rows given in this parameter --return all projects except the first 10
when returning results. This is useful in
combination with “top” to implement paging (e.g. /Project?$skip=10
if using 10-entity pages, saying $skip=30&top=$10 --return the 4th page, in 10-row pages
would return the fourth page).
/Project?$skip=30&$top=10
NOTE: Skip only makes sense on sorted sets; if an
orderby option is included, ‘skip’ will skip entities
in the order given by that option. If no orderby
option is given, ‘skip’ will sort the entities by
primary key and then perform the skip operation.
top Restrict the maximum number of entities to be --top 5 projects
returned. This option is useful both by itself and in
combination with skip, where it can be used to /Project?$top=5
11. 11
implement paging as discussed in the description --top 5 projects order by Name
of ‘skip’.
/Project?$orderby=Name&$top=5
format A URI with a ‘format‘ System Query Option /Project?$format=json
specifies that a response to the request MUST use
the media type specified by the query option. /Project?$format=xml
If the ‘format‘ query option is present in a request
URI it takes precedence over the value(s) specified
in the Accept request header.
If the ‘format‘ is not specified atom+xml value is
used as default.
filter Restrict the entities returned from a query by -- all Projects with ScrumDesk name
applying the expression specified in this operator
to the entity set identified by the last segment of /Project?$filter=Name eq ‘ScrumDesk’
the URI path.
12. 12
Table 2: Operators for filter expressions
Operator Description Example
Logical Operators
eq Equal /Project?filter=Name eq 'ScrumDesk'
ne Not equal /Project?filter=Name ne 'ScrumDesk'
gt Greater than /Project?filter=DefaultSprintLength gt 30
ge Greater than or equal /Project?filter=DefaultSprintLength ge 30
lt Less than /Project?filter=DefaultSprintLength lt 30
le Less than or equal /Project?filter=DefaultSprintLength le 30
and Logical and /Project?filter=Name eq ‘ScrumDesk‘ and
DefaultSprintLength gt 30
or Logical or /Project?filter=Name eq ‘ScrumDesk‘ or
DefaultSprintLength gt 30
not Logical negation /Project?$filter=not endswith(Name,'API‘)
Arithmetic Operators
add Addition /Task?filter=TimeSpent add 5 gt 10
sub Subtraction /Task?filter=TimeSpent sub 5 gt 10
mul Multiplication /Task?filter=TimeSpent mul 5 gt 10
div Division /Task?filter=TimeSpent div 5 gt 10
mod Modulo /Task?filter=TimeSpent mod 5 eq 0
Grouping Operators
() Precedence grouping /Task?filter=(TimeSpent add 5) gt 10
13. 13
If you need more information please take a look on www.scrumdesk.com
or don’t hesitate to send email to support@scrumdesk.com.
ScrumDesk contacts
scrumdesk@scrumdesk.com
Sales: sales@scrumdesk.com
Support: support@scrumdesk.com
