• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
ScrumDesk API  Getting Started
 

ScrumDesk API Getting Started

on

  • 667 views

 

Statistics

Views

Total Views
667
Views on SlideShare
667
Embed Views
0

Actions

Likes
0
Downloads
17
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    ScrumDesk API  Getting Started ScrumDesk API Getting Started Document Transcript

    • 1ScrumDesk API Getting started April 19, 2011 v. 3
    • 2CONTENTINTRODUCTION ...................................................................................................................................... 4HOW TO USE SCRUMDESK API ................................................................................................................ 4USAGE SCENARIOS ................................................................................................................................. 41. AUTHENTICATION ................................................................................................................................ 5BASIC AUTHENTICATION ........................................................................................................................................... 52. ACCESSING PROJECTS ............................................................................................................................ 5ALL PROJECTS ......................................................................................................................................................... 5PROJECT DETAILS .................................................................................................................................................... 53. RELEASES ........................................................................................................................................... 5RELEASES OF A PROJECT ........................................................................................................................................... 5RELEASE DETAILS ..................................................................................................................................................... 54. SPRINTS ............................................................................................................................................. 5ALL SPRINTS OF A PROJECT........................................................................................................................................ 5SPRINT DETAILS....................................................................................................................................................... 65. STORIES ............................................................................................................................................. 6STORIES OF A PROJECT ............................................................................................................................................. 6STORIES OF A SPRINT ............................................................................................................................................... 6STORIES OF A RELEASE.............................................................................................................................................. 6STORIES ASSIGNED TO AN USER ................................................................................................................................. 6STORIES OF A PROJECT ORDERED BY SELECTED ATTRIBUTES ............................................................................................. 6SELECTION OF THE FIRST N STORIES OF A PROJECT ........................................................................................................ 6SELECTION OF ANY N STORIES OF A PROJECT ................................................................................................................ 6STORY DETAILS ....................................................................................................................................................... 76. TASKS ............................................................................................................................................... 7TASKS OF A STORY ................................................................................................................................................... 7TASK DETAILS ......................................................................................................................................................... 77. TEAM MEMBERS .................................................................................................................................. 7GET TEAM MEMBERS ............................................................................................................................................... 7TEAM MEMBER DETAILS ........................................................................................................................................... 78. CREATE A NEW ENTITY ........................................................................................................................... 7UPDATE AN ENTITY ................................................................................................................................ 8MERGE-BASED UPDATE ............................................................................................................................................ 8REPLACE-BASED UPDATE .......................................................................................................................................... 9DELETE AN ENTITY .................................................................................................................................. 9
    • 3APPENDIX ............................................................................................................................................ 10
    • 4IntroductionScrumDesk 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 possibleto install it in local environment and connect it with data stored in the company environment.How to use ScrumDesk APIThe ScrumDesk API is a platform as a service. All information are provided by web data service. To learnhow 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 asJSON or XML data form. Different API calls use different HTTP verbs like GET, POST, PUT and DELETE. If youwant to send request or receive response in JSON format you must add Accept:application/json tag intohttp 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 youuse ScrumDesk API installed on our server (hosting.scrumdesk.com) the base url ishttp://hosting.scrumdesk.com:81/WebAPI/ScrumDesk.svc. If you use your installation of ScrumDesk APIthe base url is http://address_of_your_server:port_number/WebAPI/ScrumDesk.svcUsage scenariosFollowing paragraphs will guide you through a simple usage how to get and work with data accessible byScrumDesk API.Our example describes basic steps covering typical workflow in which your application can call API toprovide fundamental functionality of scrum project management tool. Authenticate Projects Project Team members Stories Story details Tasks
    • 51. AuthenticationBasic authenticationBasic authentication verifies user against ScrumDesk database and caches authenticated user in servercache. You need to specify repository (database) as part of user login name.Example: User authenticationDatabase name: ScrumDeskDatabaseNameUser name: ScrumDeskUserNameLogin: ScrumDeskDatabaseNameScrumDeskUserName2. Accessing projectsAll projectsList all projects stored in a customer database{BaseURL}/ProjectProject detailsGet details of particular project. Project Id can be recognized by call of Get all projects{BaseURL}/Project(projectID)3. ReleasesReleases of a projectList all releases of particular project{BaseURL}//Project(projectID)/ReleaseRelease detailsList attributes of particular release{BaseURL}//Project(projectID)/Release(releaseID)4. SprintsAll sprints of a projectList all sprints of particular project
    • 6{BaseURL}//Project(projectID)/SprintSprint detailsList attributes of particular sprint{BaseURL}//Project(projectID)/Sprint(sprintID)5. StoriesStories of a projectList all stories in backlog of a project{BaseURL}//Project(projectID)/Task?$filter=ParentTaskId eq nullStories of a sprintList all stories that belong to particular sprint{BaseURL}/Project(projectID)/Sprint(sprintID)/Task?$filter=ParentTaskId eq nullor{BaseURL}//Project(projectID)/Task?$filter=SprintId eq sprintID and ParentTaskId eq nullStories of a releaseList all stories that belong to particular release{BaseURL}//Project(projectID)/Release(releaseID)/Task?$filter=ParentTaskId eq nullor{BaseURL}//Project(projectID)/Task?$filter=ReleaseId eq releaseID and ParentTaskId eq nullStories assigned to an userList all stories that are assigned to particular user{BaseURL}//Project(projectID)/Task?$filter=User/Id eq userID and ParentTaskId eq nullStories of a project ordered by selected attributesList all stories in backlog of a project ordered by Importance and Subject{BaseURL}//Project([projectID)/Task?$orderby=Importance,Subject&$filter=ParentTaskId eq nullSelection of the first N stories of a projectList 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=nSelection of any N stories of a projectList any n stories in backlog of a project, n is number of stories to be displayed, m is number of stories to beskipped{BaseURL}//Project([projectID)/Task?$filter=ParentTaskId eq null&$skip=m&$top=n
    • 7Story detailsList attributes of particular story{BaseURL}//Project(projectID)/Task(taskID)6. TasksTasks of a storyList all tasks that belong to particular story{BaseURL}//Project(projectID)/Task(storyID)/Task1Task detailsList attributes of particular task{BaseURL}//Project(projectID)/Task(storyID)/Task1(taskID)7. Team membersGet team membersTeam members are allowed to access project’s data. This API method allows to get the list of all teammembers of a project.{BaseURL}/Project(projectID)/ProjectUsersTeam member detailsList attributes of particular team member. The ID of team member can be recognized using Get projectteam 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)/UserThere is a possibility to get all information about team member at once. To get all details of an userincluding team member details call:{BaseURL}/Project(projectID)/ProjectUsers(projectUserID)?$expand=User8. Create a new entityTo create a new entity (data), an HTTP POST request needs to be sent to the URI that points to thecontainer for that entity.For example to create a new Release object you would send an HTTP POST request to the /Release URIcontainer (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 tointerpret the data appropriately. Not all the properties of a given entity type need to be included; thosenot included will take their default value in the server. If a given property is not nullable the createoperation will fail.
    • 8After processing the POST request, the data service will return the entity that was created, with all of itsvalues 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 releaseHTTP request: POSTURL: {BaseURL}/Project(projectID)/ReleaseRequest headers:accept: application/atom+xmlcontent-type: application/atom+xmlRequest 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 entityThere are two possible options for updating existing entities:  a merge-based update  a replace-based updateMerge-based updateAn existing entity can be modified by sending an HTTP MERGE request to the URI where the entity islocated. 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 theproperties that are being modified. If a property is not included, the value that is currently present in theserver will be preserved. The response from an HTTP PUT request is a 204 (No Content) HTTP response.
    • 9Example 2 – Update release (using merge-based update):HTTP request: MERGEURL: {BaseURL}/Project(projectID)/Release(75)Request headers:accept: application/atom+xmlcontent-type: application/atom+xmlRequest 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 updateAn existing entity can be modified (updated) by sending an HTTP PUT request to the URL where the entity islocated. 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 theproperties of the entity (not including navigation properties). If a property is not included, the value is reseton the server to the default value for the property.Delete an entityEntities are deleted by executing an HTTP DELETE request against the URL that identifies the entity in thedata 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 therequest will be answered as success (HTTP status 204 (No Content)), without further details.Example 3:HTTP request: DELETEURL: {BaseURL}/Project(projectID)/Release(75)
    • 10AppendixTable 1: Query string optionsOption Description Exampleexpand 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 implement paging as discussed in the description --top 5 projects order by Name of ‘skip’. /Project?$orderby=Name&$top=5format 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.
    • 12Table 2: Operators for filter expressionsOperator Description ExampleLogical Operatorseq Equal /Project?filter=Name eq ScrumDeskne Not equal /Project?filter=Name ne ScrumDeskgt Greater than /Project?filter=DefaultSprintLength gt 30ge Greater than or equal /Project?filter=DefaultSprintLength ge 30lt Less than /Project?filter=DefaultSprintLength lt 30le Less than or equal /Project?filter=DefaultSprintLength le 30and Logical and /Project?filter=Name eq ‘ScrumDesk‘ and DefaultSprintLength gt 30or Logical or /Project?filter=Name eq ‘ScrumDesk‘ or DefaultSprintLength gt 30not Logical negation /Project?$filter=not endswith(Name,API‘)Arithmetic Operatorsadd Addition /Task?filter=TimeSpent add 5 gt 10sub Subtraction /Task?filter=TimeSpent sub 5 gt 10mul Multiplication /Task?filter=TimeSpent mul 5 gt 10div Division /Task?filter=TimeSpent div 5 gt 10mod Modulo /Task?filter=TimeSpent mod 5 eq 0Grouping Operators() Precedence grouping /Task?filter=(TimeSpent add 5) gt 10
    • 13If 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