ShareDo is constructed on an ‘API first’ basis. What this means in practice is that every piece of functionality that is available in the ShareDo UX is also available via a REST API. There are currently more than 400 API endpoints available for use that enable every piece of functionality that can be performed through the UI to be also achieved through system-to-system integration.

In addition a subset of these APIs are also made available via a versioned public API; and it is typically these APIs that should be used when building external system integrations.

The /public/ moniker on the APIs indicates this, and provides for clear separation between the 400+ internal APIs and the APIs meant for consumption by integrations. In addition, every API exposed from /public/ will be versioned and will provide for swagger/openApi descriptors.

These APIs are designed for easy discovery and cohesion with a general url nomenclature of;

/api/public/{area}/{version}/{resource}/{id}/{subResource}/{id}/{subResource}/{id}… Etc

And

/api/public/{area}/{version}/{rpc}

/api/public/{area}/{version}/{resource}/{id}/{rpc}

VERSIONING

Versioning is typically performed at the resource level e.g. people, users, work item. Where an API is not marked as depreciated its continuing backwards compatibility can be relied upon.

SUB RESOURCES

The concept of resource/sub resource is to address into other items within a top level aggregate. For example, a work item instance;

GET /api/public/workItems/v1/{id} = Would get you the base ShareDo data for the id specified.

PUT /api/public/workItems/v1/{id} = Would update the base ShareDo data

GET /api/public/workItems/v1/{id}/participants = Would get you the list of participants on that work item instance.

POST /api/public/workItems/v1/{id}/participants = Would create a new participant on the work item

GET /api/public/workItems/v1/{id}/participants/{id} = Would get a specific participant sub-resource on the main work item resource.

GET /api/public/workItems/v1/{id}/comments = Would get you a list of comments on the work item instance…

So, for addressable resources, HTTP verbs used to effectively do CRUD operations on those resources. The exceptions to this pattern are RPCs - remote procedure calls. These are common groups of logic that don’t fit with a simple GET/PUT/POST/DELETE/PATCH for a resource. For instance, the operation to delegate a task involves creating some new participants and reassigning existing ones. For this type of operation we have RPC calls, which are addressed in a similar way to resources, but only support a PUT, POST or DELETE depending on what they are doing.

POST /api/public/workItems/v1/{id}/{rpc}

e.g.

POST /api/public/workItems/v1/{id}/delegate
{
“role”: “primary-owner”,
“delegation-role”: “delegated-by”,
“to”: “{new owner ods id}”
}

SETTING UP AN OATH CLIENT

Within the Admin area of ShareDo you can see a list of the OAuth clients for a specific environment.

To test your authentication flow, you could use an existing client. For example, 'ee-app' (which is the client our Execution Engine uses). Note: there are a few different 'ee-app' clients, use the one circled - it is configured for the Client Credentials flow.

You'll want to create your own client once you have that working though, more on that below.

If you click 'edit' for that client, it displays a blade with the Access Token URL, ClientID and Secret (click the eye icon to display the Secret):

To test this please click the Download Postman collection button to get a preconfigured postman client configuration. This is Postman configured to get a token as the 'ee-app' client above:

That will enable you to call all of the public APIs described in this document. For some of the endpoints, your OAuth client needs specific permissions. These are mentioned in the on-line documentation for the relevant API. To manage permissions for your app, you'll want to add your own client instead of using an existing one. You can do that by clicking 'Add App' in the top-right of the Identity Server page, and then 'Add client credentials application':

That will let you specify the details of a new client, including the ClientID and Secret. You can also manage permissions for that client at the bottom of that blade:

API COVERAGE

The public API is broken down into the following areas: