Sharpcloud Logo

SharpCloud REST API (ODATA)

Summary

SharpCloud offers a Representational State Transfer (REST) API that can be used to access SharpCloud data using modern web programming tools. ODATA is our preferred way to deliver a RESTful service as it is an open industry standard that offers flexibility to make customised requests without overcomplicating the REST endpoints.

The ODATA syntax has built in functionality for filtering, sorting and pagination and is used for our internal admin pages as it is simple and very powerful. If you are not familiar with ODATA you can find out more here https://www.odata.org/.

The new API is public facing and designed to be used by external services (and SharpCloud) to make reads and updates to specific data points in a much more efficient way. This simplifies the data model for developers and speeds up reads and writes because the entire story does not need to be loaded to make a small change.

As it is new (and in beta), it does not yet allow everything to be done from our web client. That said, it does quite a lot already, and we are adding more features to it every day.

If more functionality is needed than is currently available, please contact us on support@sharpcloud.com, or take a look at our SDK (more details below). It offers a .NET library that can be used in desktop applications to make batch read or updates.

For those that want to jump straight in, here is the swagger page https://my.sharpcloud.com/swagger

Authentication

We currently support BasicAuth and Token based Authentication, and either may be used depending on the use case.

When writing a batch application or service that needs to talk to SharpCloud but is not delivered via a browser, Basic Auth will provide the simplest solution. Be aware that the Basic Auth password is set independently if the normal SharpCloud account is linked to O365, and you will be responsible for storing your credentials safely.

When writing something that is delivered via the browser, then you can simply login to SharpCloud and use the cookies generated by the sign in process, or perhaps more significantly, the current users’ credentials will be used.

In a future version we expect to support OAUTH and may then stop supporting basic auth altogether.

API access is available through any normal user account that has an active SharpCloud subscription.

Access Control

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

Licence

Anyone with an active subscription (small business or enterprise, or trial) can access data using the API, 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 are affected by this.

Read Requests: Currently there is no limit on the number of read requests or volume of data that can be extracted from the API. SharpCloud fair usage policy applies.

Write requests: Limited to 60 per hour by default. The restriction can be removed by contacting us.

Documentation

The swagger page lists all the available endpoints, variable types and allows you try out snippets of code. https://my.sharpcloud.com/swagger

We will be creating a library of useful code snippets and these will be available soon.

Roadmap

Visit our roadmap to learn more about our plans and help us make SharpCloud work for you.

The SDK

The SDK is also an API. It is a .net component that can be downloaded for free from Nuget (https://www.nuget.org/packages/SharpCloud.ClientAPI/). Unlike the REST API, this component allows you to access the entire story object model (items, attributes, relationships panels etc) in one place. It requires a .NET (v4.5) environment, limiting its appeal for some use cases, but it is ideal for batch type operations and you can find many examples on github here: https://github.com/sharpcloud

The SDK is great for building desktop and console applications that run as disconnected applications. See examples here: https://my.sharpcloud.com/html/#/story/a73b29e6-44e1-4f4f-991c-d9b0292713d4/view/2d679f8f-1fac-4b04-9a1d-f5e0ef32c5a4

Click here to see a short video on getting started. https://www.youtube.com/watch?v=RjR5--DXD0g