REST API

From OneDesk's WIKI
Jump to: navigation, search

Contents

API Introduction

OneDesk provides Representational State Transfer (REST) web service. To use a REST API, your can make an HTTP request and parse the response. The request and response support both JSON and XML format. And our REST API supports the following methods: GET, POST, PUT and DELETE.

URI Structures

The URIs in OneDesk have the following structures:
https://domain.com:port/rest/api-name/api-version/resource-name.format?cid=organization
or
https://organization.domain.com:port/rest/api-name/api-version/resource-name.format (not implemented)

Parameters

  • organization: the organization that user wants to access.
  • domain.com:port: the service host (api.onedesk.com).
  • api-names: Currently, our REST API has two available api-names: “auth” and “core”:
  • The REST endpoint in “auth” is to access authentication related information.
  • The REST endpoint in “core” is to access all other information(user’s credential is required).
  • api-version: The current api-version is 1.0
  • resource-name: defines which resource that user wants to access, such as: feedback, login, or space.
  • format: defines the expected response body’s format. There are two formats available: xml or json. By default, our system uses json.

Notes & Examples

Note 1: The format can also be defined in HTTP header(header name: ACCEPT, value: application/xml or application/json). However, the definition in URI has higher priority.
Note 2: OneDesk APIs requires URL encode.
Example 1: https://api.onedesk.com/rest/auth/1.0/login.xml?cid=org1
Example 2: https://org1.api.onedesk.com/rest/auth/1.0/login.xml

Check Service API

URI

https://api.onedesk.com/rest/core/#.#/info{.format}?{cid=orgnization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response body:json or xml

Method GET

This request is to retrieve REST service connection status. It returns the connection information in json/xml format.
example: https://api.onedesk.com/rest/core/1.0/info.json?cid=org1
Note:In this request, the api-version can be any number in the format: “digit.digit”. However, in other requests, only api-version 1.0 is available.

Available responses

  • 200 OK

Response body example

 {
   "serverConnection":true,
   "requestInfo":{
      "contentType":"JSON",
      "version":"1.0",
      "authenticationDetails":{
         "cid":"org1"
      },
      "apiType":"CORE"
   },
   "serverInfo":"Server says Ok"
 }
  • 404 Not found -The requested organization does not exist

Authentication APIs:

Login


https://api.onedesk.com/rest/auth/1.0/login{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
login required String a registered user’s email
password required String a registered user’s password
clazz required UserType enum defines this user’s type: User or CustomerUser
format optional String defines the response’s type:json or xml

Method POST

Send a login request to the server. The request contains user's name, password and user type. This method is specially for browser based API clients with cookies support.
Available user types:User and CustomerUser
Request:
type 1:application/json

 {
   login:"email@example.com",
   password:"123456",
   userIdentity:{clazz:"User"}
 }

type 2:application/xml

 <AuthenticationDetails>
 <login>email@example.com</login>
 <password>123456</password>
 <userIdentity>
 <clazz>User</clazz>
 </userIdentity>
 </AuthenticationDetails>

Available responses

  • 200 OK

Response body example

 { 
   "authId":ad123,
   "id":10001,
   "clazz":"User",
   "organizationId":1
 }

The response body contains an authId, which can be used to authenticate the user’s identity. So for the following requests, instead of sending username and password, user can use this authId in the URL. example:https://api.onedesk.com/rest/core/1.0/items/getItems?cid=org1&authId=ad123&handlers=BlogPost.1

Logout


https://api.onedesk.com/rest/auth/1.0/logout{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to log out of.
format optional String defines the response body:json or xml

Method GET

log out from the current session. Available user types:User and CustomerUser
Available responses

  • 204 No content

Reset Password


https://api.onedesk.com/rest/auth/1.0/resetPassword{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
login required String a registered user’s email
format optional String defines the response’s type:json or xml

Method POST

Send a reset password request to the system. System will check the provided email address. If it is a registered email, system will send an email to this address, which includes a link to reset password.
Available user types:User and CustomerUser.
Request:
type 1: application/json

 {
   login:“email@example.com}

type 2:application/xml

 <AuthenticationDetails>
 <login>email@example.com</login>
 </AuthenticationDetails>

Available responses

  • 204 No content

Registration


Register New User: https://api.onedesk.com/rest/auth/1.0/register{.format}
Register New CustomerUser: https://api.onedesk.com/rest/auth/1.0/register{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required if clazz = CustomerUser String the organization that customer wants to join
login required String the new user’s email
clazz required UserType enum defines this user’s type:User or CustomerUser
format optional String defines the response’s format:json or xml

Method POST

Send this request to sign up a new account. The request body contains a valid email address, and the user's type. There are two kinds of user types available: User or CustomerUser.
If sign up as an User: system will create a new organization for this user.
If sign up as a CustomerUser: the new customer will join in an existing organization.
When the request succeeds, the new user/customer will receive an email which include a link to confirm the registration.

Request:
type 1: application/json

 {
   login:“email@example.com,
   userIdentity:{ clazz:“User”}
 }

type 2: application/xml

 <AuthenticationDetails>
 <login>email@example</login>
 <userIdentity>
 <clazz>CustomerUser</clazz>
 </userIdentity>
 </AuthenticationDetails>

Available responses

  • 201 Created -Return the new user’s id

CORE API Items

Get Item

note: this method is deprecated. user now can use getItems to query sign item.


https://api.onedesk.com/rest/core/1.0/items/getItem{.format}?{cid=organization}&{handler=Class.id}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
handler required String.number the item that user wants to get. Use item class and id to specify this item.
format optional String defines the response’s format:xml or json

Method GET

Get a specific item’s information. The handler's format is the item's class plus the item' id (case sensitive). This request needs user’s authentication. Auth type is Basic.
Available user types:User and CustomerUser
Here is the list of available item classes.

example: https://api.onedesk.com/rest/core/1.0/items/getItem?&cid=org1&handler=Feedback.1


Available responses

  • 200 OK

Response body example

 {
   "name":"Tradeshow fees are not quite accurate",
   "source":"CUSTOMER_PORTAL",
   "container":{
      "id":275,
      "clazz":"FeedbacksContainer"
   },
   "organization":{
      "id":1,
      "clazz":"Organization"
   },
   "duplicates":{
      "source":[
      ]
   },
   "tags":{
      "source":[
      ]
   },
   "created":1274893311378,
   "edited":1274893311378,
   "customerPriority":80,
   "customFields":{
      "source":[
      ]
   },
   "relatedRequirements":{
      "source":[
         {
            "id":20010,
            "clazz":"Requirement"
         },
         {
            "id":20004,
            "clazz":"Requirement"
         }
      ]
   },
   "relatedTasks":{
      "source":[
      ]
   },
   "estimatedRevenue":{
      "currencyCode":"USD",
      "amount":0
   },
   "isPublished":true,
   "votes":{
      "source":[
         {
            "id":1910943,
            "clazz":"Vote"
         }
      ]
   },
   "score":1,
   "rank":980.7385663257222,
   "published":1274893311378,
   "positiveVotes":1,
   "negativeVotes":0,
   "attachments":{
      "source":[
      ]
   },
   "author":{
      "id":10007,
      "clazz":"User"
   },
   "discussionPostsCount":0,
   "communityDiscussionPostsCount":0,
   "organizationalId":1,
   "commentOnPublishedFeedback":"ON",
   "socialMediaResults":{
      "source":[
      ]
   },
   "lifecycleStatus":{
      "id":27263,
      "clazz":"PropertyCustomValue"
   },
   "id":441,
   "clazz":"IdeaFeedback"
 }
  • 404 Not found -The item doesn’t exist.

Get Items


https://api.onedesk.com/rest/core/1.0/items/getItems{.format}?{cid=organization}&{handlers=Class.id1,Class.id2,Class.id3}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
handlers required String.number the items that user wants to get. Use item class and id to specify these items
format optional String defines the response’s format:xml or json

Method GET

This request is similar to the “Get Item” request, but can apply for multiple items. This request needs user’s authentication. Auth type is Basic.
Available user types:User and CustomerUser

Here is the list of available item classes.

example: https://api.onedesk.com/rest/core/1.0/items/getItems?cid=org1&handlers=BlogPost.1,Feedback.10
Available responses

  • 200 OK -Return all the requested items. The items in response body are ordered randomly. If the requested items don't exist, the response body will be blank


fulltext search


https://api.onedesk.com/rest/core/1.0/items/search{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
query optional String defines the full text search keyword
entities required String specify the item classes that will be searched
itemsPerPage optional Integer items per page. Default value is 10
page optional Integer page number. Default value is 1
orderby optional String order the results by a selected property
order optional ASC | DESC decides the order to be ascending or descending. Default value is ASC. It works together with orderby
lazy optional Boolean decides the nested properties should be loaded or not. Default value is true

Method POST

This fulltext search searches all the items and returns the items with the defined keyword and item classes. When there is no query keyword, this search will return all the items with the defined item classes. This request needs user’s authentication. Auth type is Basic.
Available user types:User and CustomerUser
Here is the list of available item classes.

Request:
type 1: application/json

{query: "test", 
 entites:["Feedback", "BlogPost"],
 itemsPerPage:3,
 page:2,
 orderby:"id",
 order: "ASC",
 lazy: true
}

Available responses

  • 200 OK



Search


Supported resources

Resource URI
Feedbacks /core/1.0/feedbacks/search
Posts /core/1.0/posts/search
ProjectTasks /core/1.0/tasks/search
Requirement /core/1.0/requirement/search
Projects /core/1.0/projects/search
Spaces /core/1.0/spaces/search
Tags /core/1.0/tags/search

URI: Search for User

https://api.onedesk.com/rest/core/1.0/{resource}/search{.format}?{cid=organization}&{q=}&{rpp=}&{p=}&{orderby=}&{order=}&{lazy=}&{item_related_properties=}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
resource required String the available resources that can be searched by users or customers
format optional String defines the response’s format:xml or json
rpp optional Integer items per page. Default value is 10
p optional Integer page number. Default value is 1
orderby optional String order the results by a selected property
order optional ASC | DESC decides the order to be ascending or descending. Default value is ASC. It works together with orderby
lazy optional Boolean decides the nested properties should be loaded or not. Default value is true
item_related_properties optional resource's searchable properties. Used to filter the searching results.

Method GET

Search items from a specific resource. This request needs user’s authentication. Auth type is Basic.

Here is the lists of resources and their available item related properties
Note: If the resource is feedback, the available user type is:User. Otherwise, the available user type: User and CustomerUser.
example: https://api.fset.me/rest/core/1.0/feedbacks/search?cid=org1&q=test&name=example
Available responses

  • 200 OK

URI: Search for CustomerUser

https://api.onedesk.com/rest/core/1.0/{resource}/searchForCustomer{.format}?{cid=organization}&{q=}&{rpp=}&{p=}&{orderby=}&{order=}&{lazy=}&{item_related_properties=}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
resource required String the available resources that can be searched by users or customers
format optional String defines the response’s format:xml or json
rpp optional Integer items per page. Default value is 10
p optional Integer page number. Default value is 1
orderby optional String order the results by a selected property
order optional ASC | DESC decides the order to be ascending or descending. Default value is ASC. It works together with orderby
lazy optional Boolean decides the nested properties should be loaded or not. Default value is true
item_related_properties optional resource’s searchable properties. Used to filter the searching results.

Method GET

Customer sends this request to search items from a specific resource. This request needs user’s authentication. Auth type is Basic. Currently, our system only support searching for the resource: feedbacks.
Here is the feedback's item related properties
Available user types:CustomerUser
Available responses

  • 200 OK

Core API Concrete Items

Supported Items

Item URI Supported methods
Feedbacks /core/1.0/feedbacks/*

GET /{id}[.xml|.json]
POST /[.xml|.json]
PUT /{id}[.xml|.json]
DELETE /{id}[.xml|.json]
GET /search[.xml|.json]
GET /searchForCustomer[.xml|.json]

Organization /core/1.0/organization/*(not implemented)

GET /{id}[.xml|.json]

Posts /core/1.0/posts/*

GET /{id}[.xml|.json]
POST /[.xml|.json]
PUT /{id}[.xml|.json]
DELETE /{id}[.xml|.json]
GET /search[.xml|.json]

Project /core/1.0/projects/*

GET /{id}[.xml|.json]
GET /search[.xml|.json]

ProjectTasks /core/1.0/tasks/*

GET /{id}[.xml|.json]
POST /[.xml|.json]
PUT /{id}[.xml|.json]
DELETE /{id}[.xml|.json]
GET /search[.xml|.json]

Requirement /core/1.0/requirement/*

GET /{id}[.xml|.json]
POST /[.xml|.json]
PUT /{id}[.xml|.json]
DELETE /{id}[.xml|.json]
GET /search[.xml|.json]

Requirements /core/1.0/requirements/*(not implemented)

GET /{id}[.xml|.json]

Spaces /core/1.0/spaces/*

GET /{id}[.xml|.json]
PUT /{id}[.xml|.json]
GET /search[.xml|.json]

Votes /core/1.0/votes/*

PUT /vote[.xml|.json]?handler={handler}[&vote=true|false]
PUT /unvote[.xml|.json]?handler={handler}

Feedbacks


https://api.onedesk.com/rest/core/1.0/feedbacks/{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
name required String feedback’s name
clazz required String defines the feedback’s type: Feedback, IdeaFeedback, ProblemFeedback, QuestionFeedback, ComplimentFeedback and LeadFeedback.
container optional Object decides which sharespace the feedback belongs to. Format: container:{id:"",clazz:"FeedbacksContainer"}

Here are the optional properties that can be used in create a feedback and/or update a feedback: Feedback's other available properties


Method POST
Create a new feedback. Request body contains the new feedback’s name, type and other optional properties. This request needs user’s authentication. Auth type is Basic
Available user types:User and CustomerUser.
User can put feedback in a specific sharespace, by using the feedback's container. Otherwise, the feedback will go to All feedback page.
CustomerUser can only put feedback in All feedback page.
example: https://api.onedesk.com/rest/core/1.0/feedbacks/.json?cid=org1
Request:
type 1: application/json

 {
   name:“test”,
   clazz:“Feedback”,
   container:{
      id:123,
      clazz:“FeedbacksContainer”
   },
   content:"sample"
 }

type 2: application/xml

 <Feedback>
 <name>test</name>
 <content>sample</content>
 <container>
 <id>123</id>
 <clazz>FeedbacksContainer</clazz>
 </container>
 </Feedback>

Available responses

  • 201 Created -Return the feedback’s handler:

type 1: application/josn

 {id: 1, clazz: "Feedback"}

type 2: application/xml

 <Handler><id>1</id><clazz>Feedback</clazz></Handler>



https://api.onedesk.com/rest/core/1.0/feedbacks/{id}{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long the feedback’s id


Method GET
Get a specific feedback by its id. This request needs user’s authentication. Auth type is Basic.
Available user types:User and CustomerUser.
Available responses:

  • 200 OK -Return the requested feedback’s information
  • 404 Not found -When the requested feedback does not exist


Method PUT
Update an existing feedback by its id. In the request body, user needs to specify this feedback's type together with the properties that user wants to update. This request needs user’s authentication. Auth type is Basic.
Available user types:User
Note: User can update any feedback's available property, except the the feedback's clazz and container.
Request:
type 1: application/json

 {
   clazz:“IdeaFeedback”,
   property1:“sample1”,
   property2:“sample2”
 }

type 2: application/xml

 <IdeaFeedback>
 <property1>sample1</property1>
 <property2>sample2</property2>
 </IdeaFeedback>

Available responses:

  • 200 OK
  • 404 Not found -When the requested feedback does not exist


Method DELETE
Delete a specific feedback. This request needs user’s authentication. Auth type is Basic.
Available user types:User
Available responses:

  • 204 No content
  • 404 Not found -When the requested feedback does not exist

Posts


https://api.onedesk.com/rest/core/1.0/posts/{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
title required if clazz=BlogPost String This parameter is only valid when post’s type is BlogPost, and it defines the BlogPost’s title.
clazz required String defines the post’s type: BlogPost, DiscussionPost, and CommunityDiscussionPost
relatedItem required Object defines which item the post belongs to. Format is:relatedItem:{id:" ",clazz:" "}

Here are the optional properties that can be used in create a post and/or update a post: Post's other available properties
Method POST
Create a new post. There are three kinds of post: BlogPost, DiscussionPost and CommunityDiscussionPost. If post’s type is BlogPost, relatedItem refers to the sharespace which user wants to publish blog. So the relatedItem's id should be the space's id, and the clazz should be: Space. If post type is CommunityDiscussionPost, relatedItem refers to the feedback which user wants to post discussion. The relatedItem's id should be the feedback's id, and the clazz should be the feedback's type. The post type Discussion is similar to the type CommunityDiscussion, but it is also applicable to requirement, issue and task.
This request needs user's authentication. Auth type is basic.
Available user types: User and CustomerUser
Request:
type 1: application/json

 {
   relatedItem:{
      id:"123",
      clazz:"Space"
   },
   content:"example",
   clazz:"BlogPost"
 }

type 2: application/xml

 <DiscussionPost>
 <content>example</content>
 <relatedItem>
   	 <id>123</id>
   	 <clazz>ProblemFeedback</clazz>
 </relatedItem>
 </DiscussionPost>

Available responses:

  • 201 Created -Return the post’s handler:

type 1: application/json

 {id:1, clazz:"BlogPost"}

type 2:

 <Handler><id>1</id><clazz>BlogPost</clazz></Handler>

https://api.onedesk.com/rest/core/1.0/posts/{id}{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long the post’s id

Other available properties:
Method GET
This request is to get a specific post by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 200 OK -Return the requested post’s information
  • 404 Not found -When the requested post does not exist


Method PUT
Update an existing post by its id. The request body requires the post’s type and the properties that user wants to update.
This request needs user's authentication. Auth type is basic.
Available user types: User
Note: User can update any available property, except the post’s type and relatedItem.
Request:
type 1: application/json

 {
   clazz:"BlogPost",
   name:"sample1",
   content:"sample2"
 }

type 2: application/xml

 <BlogPost>
 <name>sample1</name>
 <content>sample2</content>
 </BlogPost>

Available responses:

  • 200 OK
  • 404 Not found -When the requested post does not exist


Method DELETE
Delete a specific post by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Note: When a post is deleted, it still stored in the system, with a property "isDeleted" set to true. So user can undo this deletion by updating this property.
Available responses:

  • 204 No content
  • 404 Not found when the requested post does not exist

Project


https://api.onedesk.com/rest/core/1.0/projects/{id}{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long the project’s id

Method GET
Gets a specific project’s information by its id.
This request needs user’s authentication. Auth type is Basic.
Available user types:User
Available responses:

  • 200 OK -Returns the project’s information, such as: resource, preference, and tasks

ProjectTask


https://api.onedesk.com/rest/core/1.0/tasks/{.format}?{cid=orgnaization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
name required String defines the issue/task’s name
project required Object defines which project the task belongs to. The format is: project:{id:" ",clazz:"Project"}
type optional TaskType defines the item's type:ISSUE or TASK. Default value is TASK.

Here are the optional properties that can be used in create an issue/task and/or update an issue/task: Issue/Task's other available properties
Method POST
Create a new issue/task in a project. The request body contains the issue/task's name, project and other properties. To specify a project, user needs to know a project's id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Request:
type 1:application/json

 {
   name:"example1",
   type:"ISSUE",
   description:"abcdef",
   project:{
      id:"1",
      clazz:"Project"
   }
 }

type 2: application/xml

 <ProjectTask>
 <name>example 1</name>
 <description>123456</description>
 <project>
 <id>1</id>
 <clazz>Project</clazz>
 </project>
 </ProjectTask>

Available responses:

  • 201 Created -Return the task’s handler:

type 1:

 {id:1, clazz:"ProjectTask"}

type 2:

 <ProjectTask><id>1</id><clazz>ProjectTask</clazz></ProjectTask>



https://api.onedesk.com/rest/core/1.0/tasks/{id}{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long task’s id

Method GET
Get a specific issue/task by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 200 OK -Return the requested task’s information
  • 404 Not found -When the requested task does not exist


Method PUT
Update an existing issue/task by its id. The request body requires the properties that user wants to update.
This request needs user's authentication. Auth type is basic.
Available user types: User
Request:
type 1: application/json

 {
   property1:"sample1",
   property2:"sample2"
 }

type 2: application/xml

 <ProjectTask>
 <property1>sample1</property1>
 <property2>sample2</property2>
 </ProjectTask>

Available responses:

  • 200 OK
  • 404 Not found -When the requested task does not exist


Method DELETE
Delete a specific issue/task by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 204 No content
  • 404 Not found -When the requested task does not exist


Create worklog


https://api.onedesk.com/rest/core/1.0/tasktimesheet/?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
assignment required assignment VO this assignment’s id and type
start required Long the worklog’s start date
work required Double the performed work in this worklog
percentCompleteReported required Double the current completion of this assginment

Method POST
Create a worklog for a specific issue/task.
This request needs user's authentication. Auth type is basic.
Available user types: User
Notes:
1. User can only create worklog for assignment that belongs to current user.
2. User can get an issue/task by its id, and find the assignment id in the response body.
Request:
type 1: application/json

 {
  assignment:{id:"111",clazz:"ProjectTaskAssignment"},
  start:"1341460800000",
  work:"1", 
  percentCompleteReported:"10"}
 }

type 2: application/xml

 <ProjectTaskTimesheet>
 <assignment>
 <id>111</id>
 <clazz>ProjectTaskAssignment</clazz>
 </assignment>
 <start>1341460800000</start>
 <work>1</work>
 <percentCompleteReported>10</percentCompleteReported>
 </ProjectTaskTimesheet>

Available responses:

  • 201 Created -Returns the worklog's id and clazz

Space


https://api.onedesk.com/rest/core/1.0/spaces/{id}{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long space id

Here are the optional properties that can be used to update a space: Space's other available properties
Method:GET
Get a specific space’s information by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 200 OK -Return the requested space’s information


Method:PUT
Update an existing space's properties by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Request:
type1: application/json

 {
   property1:"sample1",
   property2:"sample2"
 }

type2: application/xml

 <Space>
 <property1>sample1</property1>
 <property2>sample2</property2>
 </Space>

Available responses:

  • 200 OK
  • 404 Not found -The requested sharespace does not exist

Requirement


https://api.onedesk.com/rest/core/1.0/requirement/{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
id required Long the project’s id
format optional String defines the response’s format:xml or json
name required String defines the task’s name
requirements required Object defines which requirements it belongs to. The format is: requirements:{id:" ",clazz:"Requirements"}

Here are the optional properties that can be used in create a requirement and/or update a requirement:Requirement's other available properties
Method:POST
Create a new requirement. The request body contains requirement's name, and the requirements it belongs to. To specify a requirements, user needs to know its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Request:
type 1: application/json

 {
   name:"example",
   description:"test",
   requirements:{
      id:"123",
      clazz:"Requirements"
   }
 }

type 2: application/xml

<Requirement>
<name>example</name>
<description>test</description>
<requirements>
<id>123</id>
<clazz>Requirements</clazz>
</requirements>
</Requirement>

Available responses:

  • 201 Created -Return the requirement’s handler:

type 1: application/json

 {id:1, clazz:"Requirement"}

type 2: application/xml

   <clazz>Requirement</clazz>
   <id>1</id>




https://api.onedesk.com/rest/core/1.0/requirement/{id}{.format}?{cid=organization}

Parameter

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
id required Long the project’s id

Method:GET
Get a specific requirement by its id.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 200 OK -Return the requested requirement’s information
  • 404 Not found -The requested requirement does not exist

Method:PUT
Update a specific requirement by its id. The request body contains the properties that user wants to update.
This request needs user's authentication. Auth type is basic.
Available user types: User
Request:
type 1: application/json

 {
   property1:"sample1",
   property2:"sample2"
 }

type 2: application/xml

 <Requirement>
 <property1>sample1</property1>
 <property2>sample2</property2>
 </Requirement>

Available responses:

  • 200 OK
  • 404 Not found -The requested requirement does not exist


Method:DELETE
Delete a specific requirement.
This request needs user's authentication. Auth type is basic.
Available user types: User
Available responses:

  • 204 no content

Vote


https://api.onedesk.com/rest/core/1.0/vote{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
handler required Object defines the item's id and type that user wants to vote.The format is: handler:{id:" ", clazz:" "}
vote optional Boolean vote this item up or down.Default value is true

Method:PUT
Vote to an issue/task or feedback.
This request needs user's authentication. Auth type is basic.
Available user types: User and CustomerUser
Request:
type 1: application/json

{handler: {clazz:"Feedback",id:"123"}, vote:"true"}

type 2: application/xml

<Vote>
<handler>
<clazz>Feedback</clazz>
<id>123</id>
</handler>
<vote>true</vote>
</Vote>


Available responses:

  • 200 OK
  • 404 Not found -The item does not exist

https://api.onedesk.com/rest/core/1.0/unvote{.format}?{cid=organization}

Parameters

Parameters Requirement Type Description
cid required String the organization that user wants to access
format optional String defines the response’s format:xml or json
handler required Object defines the item's id and type that user wants to unvote.The format is: handler:{id:" ", clazz:" "}

Method:PUT
Remove current user’s vote from an issue/task or feedback.
This request needs user's authentication. Auth type is basic.
Available user types: User and CustomerUser
Request:
type 1: application/json

{handler: {clazz:"Feedback",id:"123"}}

type 2: application/xml

<Vote>
<handler>
<id>123</id>
<clazz>Feedback</clazz>
</handler>
</Vote>


Available responses:

  • 200 OK
  • 404 Not found -The item does not exist

Exception codes

  • 304 Not Modified - you requested an update, but didn't change any property
  • 400 Bad Request - you didn’t specify clazz/property for create and update methods or you have validation exception on the server side or you specified not valid argument for some property
  • 401 Unauthorized - if you are not logged in
  • 403 Forbidden - if you don't have permission
  • 404 Not Found - if your requested page doesn’t exist, or your requested item doesn’t exist
  • 405 Method Not Allowed
  • 501 Not Implemented exception - you are trying do operation that wasn’t implemented
  • 500 Internal server error - for all other cases


With any exception server returns message in following format:

Your activity was recorded: <<number>>

Where <<number>> is Exception tracking number. We store all unsuccessful activities. You could submit feedback with this tracking number and we will able find it and analyze this concrete case.

Personal tools