|
|
|
|
Authentication All API requests must contain some mechanism for identifying the user and ensuring they are authorized to make the request. The TeamPulse API uses the Username and Password to authenticate the user. Errors Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information. 200 | Success. If data was requested, it will be available in the data field at the top level of the response body. | 201 | Success (for object creation). Its information is available in the datafield at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response. | 400 | Invalid request. This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. | 404 | Not found. Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist. | 500 | Server error. There was a problem on our end. | In the event of an error, the response body will contain a list of erorrs. HTTP/1.1 400 Bad Request {"te.note":"The field note must be a string with a maximum length of 128."}
Users A user object represents an account in TeamPulse that can be given access to various projects.
Like other objects in the system, users are referred to by numerical IDs. Users only have a small set of fields: name | smokey
The user's username. | displayName | Smokey The Bear
The user's name. | Showing a single user GET | /users/user-id | GET | /users/me |
This method returns the full user record for a single user.
Request Response HTTP/1.1 200 OK {"id":1,"name":"smokey","displayName":"Smokey The Bear"} Showing all users
This method returns the user records, described above, for all users in all projects that you may access. Request Response HTTP/1.1 200 OK [{ "id": 1, "name": "smokey", "displayName": "Smokey The Bear" }, { "id": 2, "name": "yogi", "displayName": "Yogi The Bear" }, ... ] Showing all users in a single project GET | /projects/project-id/users |
This method returns the user records, described above, for all users in the specified project.
Request http://[teampulse]/api/projects/1/users Response HTTP/1.1 200 OK [{ "id": 1, "name": "smokey", "displayName": "Smokey The Bear" }, { "id": 2, "name": "yogi", "displayName": "Yogi The Bear" }, ... ] Projects A project is the basic organizational unit in TeamPulse. Almost everything belongs to a project - work items, tasks, etc. Project expose the following fields: name | Project 1
Name of the project. | Showing available projects Request Response HTTP/1.1 200 OK [{ "id": 1, "name": "Project 1" }, { "id": 2, "name": "Project 2" }, ... ] Tasks A task is the the item against user can log time. Tasks can have a work item and project. Tasks that doesn't have work item are general tasks in a project. Tasks that doesn't have work item or project are general tasks out of the projects. They are used to track time against Holiday or Sick Leaves for example. Tasks have a rich set of metadata associated with them, some of which is exposed via the API. Here are the accessible fields on a task: Showing a specific task Request Response HTTP/1.1 200 OK { "id": 1, "name": "Task 1", "project": { "id": 1, "name": "Project 1" }, "workItem": { "id": 1, "name": "Issue #1", "type": "Issue", "estimate": 4.0 }, "workCompleted": 3.0, "estimate": { "optimistic": 3.0, "probable": 4.0, "pessimistic": 5.0, "pert": 4.0 } } Querying for tasks GET | /tasks | GET | /projects/project-id/tasks | Request Response HTTP/1.1 200 OK [{ "id": 75090, "name": "Vacation", "project": { "id": -1, "name": "" }, "estimate": { } }, { "id": 75094, "name": "Meetings", "project": { "id": 2, "name": "Project 2" }, "workCompleted": 2.0, "estimate": { } }, { "id": 4341, "name": "Task 1", "project": { "id": 2, "name": "Project 2" }, "workItem": { "id": 505, "name": "Story 5", "type": "Story", "estimate": 4.0 }, "workCompleted": 3.0, "estimate": { "optimistic": 5.0, "probable": 10.0, "pessimistic": 15.0, "pert": 10.0 } } ... ] TimeEntries A TimeEntry is the time spend in hours on specific date for specific task and user. Creating a new TimeEntry Request function getData() { var te = { date: '2011-06-06' , hours: 1, task: { id: 1 }, user: { id: 6 }, type: 'Billable' }; return JSON.stringify(te); } $.ajax({ cache: false , type: 'POST' , contentType: 'application/json; charset=utf-8' , data: getData(), error: function (xhr, status, err) { if (xhr.status == 400) { // error in the app } else { // server error } }, success: function (data, status, xhr) { window.setTimeout( function () { alert(data); }, 10); } }); Response HTTP/1.1 201 Created { "id": 19492, "date": "2012-06-03", "hours": 2.0, "type": "Billable", "user": { "id": 14 }, "task": { "id": 8831, "workCompleted": 5.0 }, "note": "", "iversion": 0 } Showing a specific TimeEntry GET | /timeentries/timeentry-id | Request http://[teampulse]/api/timeentries/3099 Response HTTP/1.1 200 OK { "id": 3099, "date": "2012-05-16", "hours": 10.0, "type": "Non-Billable", "user": { "id": 1, "name": "smokey", "displayName": "Smokey The Bear" }, "task": { "id": 10331, "name": "Task 1", "project": { "id": 4, "name": "4_Planning" }, "workItem": { "id": 1938, "name": "Risk #438", "type": "Risk", "estimate": 9.0 }, "workCompleted": 3.0, "estimate": { "optimistic": 3.0, "probable": 4.0, "pessimistic": 5.0, "pert": 4.0 } }, "note": "Note for task id: 10331", "iversion": 1 } Updating an existing TimeEntry PUT | /timeentries/timeentry-id | Request function getData() { var te = { date: '2012-06-05' , hours: 2, task: { id: 7244 }, user: { id: 14 }, type: 'Billable' , iversion: 1 }; return JSON.stringify(te); } $.ajax({ url: 'http://[teampulse]/api/timeentries/2174' , cache: false , type: 'PUT' , contentType: 'application/json; charset=utf-8' , data: getData(), error: function (xhr, status, err) { if (xhr.status == 400) { // error in the app } else { // server error } }, success: function (data, status, xhr) { window.setTimeout( function () { alert(data); }, 10); } }); Response HTTP/1.1 200 OK { "id": 2174, "date": "2012-06-05", "hours": 2.0, "type": "Billable", "user": { "id": 14 }, "task": { "id": 7244, "workCompleted": 0.0 }, "note": "Note for task id: 7244", "iversion": 2 } Querying for TimeEntries GET | /timeentries | GET | /timeentries?startDate=date&endDate=date | Request http://[teampulse]/api/timeentries?startDate=2012-05-27&endDate=2012-06-02 Response HTTP/1.1 200 OK [{ "id": 972, "date": "2012-05-30", "hours": 3.0, "type": "Non Billable", "user": { "id": 20, "name": "smokey", "displayName": "Smokey The Bear" }, "task": { "id": 3099, "name": "Task 1", "project": { "id": 2, "name": "Project 2" }, "workItem": { "id": 515, "name": "Bug #15", "type": "Bug", "estimate": 10.0 }, "workCompleted": 3.0, "estimate": { "optimistic": 3.0, "probable": 4.0, "pessimistic": 5.0, "pert": 4.0 } }, "note": "Note for task id: 3099", "iversion": 1 },{ "id": 4545, "date": "2012-05-30", "hours": 4.0, "type": "", "user": { "id": 21, "name": "smokey", "displayName": "Smokey The Bear" }, "task": { "id": 75090, "name": "Vacation", "project": { "id": -1, "name": "" }, "estimate": { } }, "note": "Note for Vacation", "iversion": 1 }, { "id": 6499, "date": "2012-05-30", "hours": 4.0, "type": "Billable", "user": { "id": 2, "name": "yogi", "displayName": "Yogi The Bear" }, "task": { "id": 75094, "name": "Meetings", "project": { "id": 2, "name": "Project 2" }, "workCompleted": 2.0, "estimate": { } }, "note": "Note for Meetings in project id: 2", "iversion": 1 } ... ] TimeEntryTypes Querying for TimeEntryTypes GET | /projects/project-id/timeentrytypes | Request http://[teampulse]/api/projects/2/timeentrytypes Response HTTP/1.1 200 OK [{ "id": 3, "timeEntryType": { "id": 1, "name": "Billable", "iversion": 0 }, "project": { "id": 2 }, "sequenceNumber": 1, "iversion": 1 }, { "id": 4, "timeEntryType": { "id": 2, "name": "Non Billable", "iversion": 0 }, "project": { "id": 2 }, "sequenceNumber": 2, "iversion": 1 }] Activities An activity represents an entry in the stream for any users with matching notification rules. Many activities are generated by changes to work items within TeamPulse, but it is also possible to post shared messages with custom content. Querying for Activities GET | /activities | GET | /activities?isFlagged=[true|false] | Request http://[teampulse]/api/activities Response HTTP/1.1 200 OK [{ "id": 41632, "project": { "id": 1 }, "author": { "name": "jsmith", "displayName": "John Smith" }, "workItem": { "id": 34, "type": "Feedback", "isVisibleInPortal": true }, "content": "I agree with you Jane. I think this is a great idea.", "iconUrl": "http://tp:9898/UserMenu/GetCachedThumbnailedUserImage?name=jsmith", "hyperlink": "http://tp:9898/#/Project/1/GettingStarted$FeedbackId=34", "modifiedAt": "2012-07-05T21:03:09.443Z", "canComment": true, "commentType": 1 "isFlagged": false, "system": "TeamPulse", "systemEvent": "WorkItemChanged" },{ "id": 41624, "author": { "name": "jsmith", "displayName": "John Smith" }, "content": "John Smith shared:< br />Going for lunch, anyone want to come?", "iconUrl": "http://tp:9898/UserMenu/GetCachedThumbnailedUserImage?name=jsmith", "modifiedAt": "2012-07-05T21:02:33.867Z", "canComment": true, "isFlagged": false, "system": "TeamPulse", "systemEvent": "PersonalMessage" } ... ] Querying for the count of unread items Request Response HTTP/1.1 200 OK { "flagged": 1, "unflagged": 1, "total": 2 } Marking items as seen Used to indicate that activities have been viewed up to a certain point. The onlyFlagged parameter allows for indicating that only flagged items should be marked as seen. PUT | /activities/seenupto/activity-id
| PUT | /activities/seenupto/activity-id?onlyFlagged=[true|false]
| Request $.ajax({ url: 'http://[teampulse]/api/activities/seenupto/3' , cache: false , type: 'PUT' , contentType: 'application/json; charset=utf-8' , error: function (xhr, status, err) { if (xhr.status == 400) { // error in the app } else { // server error } }, success: function (data, status, xhr) { window.setTimeout( function () { alert(data); }, 10); } }); Response HTTP/1.1 200 OK { "flagged": 0, "unflagged": 0, "total": 0 } Getting a list of user names for mention suggestions GET | /activities/users | GET | /users |
Both return the same results, see getting a list of users above. Creating a new Shared message activity Request function getData() { var share = { message: 'hello world' }; return JSON.stringify(share); } $.ajax({ cache: false , type: 'POST' , contentType: 'application/json; charset=utf-8' , data: getData(), error: function (xhr, status, err) { if (xhr.status == 400) { // error in the app } else { // server error } }, success: function (data, status, xhr) { window.setTimeout( function () { alert(data); }, 10); } }); Response HTTP/1.1 201 Created { "message": "Paul Smith shared: hello world" } Comments Stories, bugs, issues, risks, and feedback can all be commented on. Feedback items can also have comments that are visible to the project portal. Creating a new comment on a work item Request function getData() { var comment = { description: 'hello world' , type: 'PortalComment' , project: { id: 1 }, workItem: { id: 1, type: 'Feedback' } }; return JSON.stringify(comment); } $.ajax({ url: 'http://[teampulse]/api/comments' , cache: false , type: 'POST' , contentType: 'application/json; charset=utf-8' , data: getData(), error: function (xhr, status, err) { if (xhr.status == 400) { // error in the app } else { // server error } }, success: function (data, status, xhr) { window.setTimeout( function () { alert(data); }, 10); } }); Response HTTP/1.1 201 Created { "id": 15, "project": { "id": 1 }, "workItem": { "id": 1, "type": "Feedback" }, "description": "I really like this one", "type": "PortalComment", "iversion": 0 }
|
|
|