Developers

Data Integration – REST API’s (Back-end) 

We can automate data flow to SharpCloud using our public REST API’s. 

Documentation 

The swagger page lists all the available endpoints, variable types and allows you to try snippets of code. If you are familiar with this concept, you can access our swagger page from the profile menu when you’re signed in as shown below: 

Authentication 

If you are already logged into SharpCloud, you can use the swagger pages as yourself (the active user). If you need to make remote calls you should generate a Personal Access Token (PAT) from your profile menu and include this as a BEARER token in your requests. The swagger page also supports adding the bearer token so you can see exactly how the underlying requests are formatted. 

Access Control 

The API has the same access control to your stories as a normal user that is accessing the stories via the browser interface and is bound by the same underlying business rules. This means that you may only read stories you have Read-Only access to and can only Create/Update/Delete from those stories that you have Collaborate/Create access on. 

License 

Anyone with an active subscription can access data using the API’s, but there are throttle limits on writes (60 per hour). The limit can be removed on a case-by-case basis so please contact us if you’re affected by these limitations. 

API’s 

SharpCloud offers two public facing API’s. In both cases, a storyID forms part of the request (i.e., the API’s always work on a specific story). Note that the API’s do not currently support Calculations which are currently performed only on the client. 

The public API’s can be broken down into two types: 

1.  Batch

2. OData

Batch API 

This is the easiest way to get large volumes of data in or out of SharpCloud. The batch API’s allow you to send and receive data in JSON format, where the content is normalized so it appears as it would to the user in the client. 

For example, the data is formatted to use friendly names (instead of their internal GUID values) such as “Category” : “Project”, “ExternalID” : “A100”, “Name” : “My Project”, “Cost” : “300”, “Risk” : “Medium” 

Using data in this format makes it much easier to work with and most developers will find it relatively easy to use. Currently the batch API’s support bulk reading and writing of: 

- Items 
- Relationships 
- Panels 
- Resources

Because the batch API’s are intended to automate data flow in and out of SharpCloud, all Items must be referenced by an ExternalID. The ExternalID is your own reference to that Item and is required to Create, Update and Delete the Item. It is a string identifier (max length of 200 characters), that you can use to reference your source system. ExternalID’s are unique per category, not per story. For example, you can have “001” as a Project Item’s ID and “001” as a Risk Item’s ID, where Project and Risk are separate categories.

Note: It is not possible to update the ExternalID via the batch API’s. 

Technically, SharpCloud does not need the ExternalID to operate and the UI will allow blanks and duplicates (internally it uses the unique GUID’s). The rules for the batch API’s are very simple; All items must specify the category that are associated to and you have to use your own unique reference (ExternalID). 

If no matching record is found, the API’s will assume you are creating a new item. If a match is found then updating will be assumed. Deletes can be called specifically (by Category and ExternalID) or by being omitted from the batch (specific options required to make this work). 

Whilst the batch API’s make it easy to move data in and out of SharpCloud in a structured way, they cannot be used to modify the story structure (e.g., adding attributes or categories). For this, you will need to use the OData endpoints. 

Importing and Exporting data is relatively easy and this is how our Data Extracts and Data Connectors communicate with SharpCloud. 

Connectors and Extracts 

Most importing or exporting of data in to and from SharpCloud can be handled using our Data Connectors and Data Extracts. It’s a powerful way of building automation flow (Extract, Transform, Load (ETL)) without any specific developer tools. 

Note: SharpCloud does not provide any tooling to “Push” data and this would need to be a developer task 

Connectors and Extracts come with a lot of advanced functionality built in to make it easy to do simple tasks. They support SQL, which allows data to be transformed before it is sent to SharpCloud, or after it has been extracted. For example, you can use the Advanced SQL to group results, perform arithmetic or join data across tables. 

Note: Connectors and Extracts are also using the public batch API’s to extract or update SharpCloud. 

OData API 

OData is a standard way to manipulate, query and join nested data. It is an open format and widely used across many scalable applications. More can be found out about it here. You can find details of our public OData API by changing the definition to “Public API V1 (ODATA)” in the top right of the swagger page. You can navigate to the swagger page from the API menu. 

Our OData API can be used to make many complex queries and although it is very powerful, it is harder to use because values are referenced using the internal identifies (GUIDs). The OData API is capable of making changes to the SharpCloud story structures like adding new categories, attributes and tags etc. For most cases, it is easier and more scalable to use the batch API’s above, but there are a few occasions when the OData API is the better or only choice, such as: 

1. You want to manipulate the story structure programmatically (add categories or attributes) 
2. You need to delete an Item that may not have an ExternalID 
3. You need to rename an Items ExternalID. 
4. You want to perform a complex or specific filter on items (E.g. All Items where Name contains “x” and AttributeValue (Cost) > 100) 

If you need more information, please contact us and let us know how we can help.