1

ScrumDesk API Getting started

April 19, 2011

v. 3

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

3

APPENDIX ............................................................................................................................................ 10

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

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: ScrumDeskDatabaseName\ScrumDeskUserName

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

{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

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

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

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

Appendix Table 1: Query string options

Option Description Example

expand The ‘expand’ option allows you to embed one or

more sets of related entities in the results.

For example, if you want to display a project user

and user attributes, you could execute two

requests, one for /ProjectUsers(1) and one for

/ProjectUsers(1)/User.

The ‘expand’ option on the other hand allows you

to return the related entities in-line with the

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.

--a project user with related user attributes

/ProjectUsers(1)?$expand=User

--a project user with related user and task

information related to this user

/ProjectUser(1)?$expand=User/Task

--Project with related releases information

and related sprints information

/Project(1)?$expand=Release,Sprint

orderby Sort the results by the criteria given in this value.

Multiple properties can be indicated by separating

them with a comma.

The sort order can be controlled by using the “asc”

(default) and “desc” modifiers.

/Project?$orderby=Name

/Project?$orderby=Name desc

/Project?$orderby=Name desc, Description

asc

skip Skip the number of rows given in this parameter

when returning results. This is useful in

combination with “top” to implement paging (e.g.

if using 10-entity pages, saying $skip=30&top=$10

would return the fourth page).

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.

--return all projects except the first 10

/Project?$skip=10

--return the 4th page, in 10-row pages

/Project?$skip=30&$top=10

top Restrict the maximum number of entities to be

returned. This option is useful both by itself and in

combination with skip, where it can be used to

--top 5 projects

/Project?$top=5

11

implement paging as discussed in the description

of ‘skip’.

--top 5 projects order by Name

/Project?$orderby=Name&$top=5

format A URI with a ‘format‘ System Query Option

specifies that a response to the request MUST use

the media type specified by the query option.

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.

/Project?$format=json

/Project?$format=xml

filter Restrict the entities returned from a query by

applying the expression specified in this operator

to the entity set identified by the last segment of

the URI path.

-- all Projects with ScrumDesk name

/Project?$filter=Name eq ‘ScrumDesk’

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

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