ScrumDesk API Getting Started
0 likes400 views
The document provides an overview of how to use the ScrumDesk API to access and manage agile project data. It describes authentication and how to retrieve information about projects, releases, sprints, stories, tasks, and team members through the API. Requests use HTTP verbs like GET, POST, PUT, and DELETE against the API URL to get, create, update, and delete data in different supported formats.
ScrumDesk API Getting Started
- 1. 1 ScrumDesk API Getting started April 19, 2011 v. 3
- 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