Getting started

The ShareBase API

ShareBase offers an easy to use REST API that allows you to quickly integrate from any platform. With the API, an application has the ability to:

• Browse the contents of libraries and folders
• Create folders and upload documents to folders
• Move folders and copy & move documents
• Download documents
• Share folder and document links
• Assign tasks on documents to individuals inside and outside your organization
• Retrieve and manage trash
• Get reports of activities performed by specific users
• Get activity reports for documents and libraries

The APIs adhere to standard HTTP semantics such as GET, POST, PATCH, and DELETE

• GET - retrieves a resource such as an item or a list of items
• POST - typically creates a new resource
• PATCH - typically updates an existing resource
• DELETE - deletes a resource

The API consists of a base URL followed by the resource path. For example:

https://app.sharebase.com/sharebaseapi/api/libraries

In this example https://app.sharebase.com/sharebaseapi is the base URL and /api/libraries is the resource path.

For purposes of this documentation, we will omit the base URL portion in the examples. For example, the request to retrieve a list of libraries would be abbreviated as:

GET /api/libraries

Which is equivalent to:

GET https://app.sharebase.com/sharebaseapi/api/libraries

ShareBase data centers

ShareBase runs in Hyland-hosted data centers all over the globe.

Each data center runs a single ShareBase instance. Customers for a particular region are hosted in that particular instance. Hyland continues to expand ShareBase into additional Hyland-hosted data centers as we grow our customer base into different regions. Each ShareBase instance has a different base URL.

• United States: https://app.sharebase.com/sharebaseapi
• Mexico: https://app.sharebase.mx/sharebaseapi
• Australia: https://app.sharebase.com.au/sharebaseapi
• United Kingdom: https://app.sharebase.co.uk/sharebaseapi
• New Zealand: https://app.sharebase.nz/sharebaseapi
• Canada: https://app.sharebase.ca/sharebaseapi

When creating an application or integrating from an existing application, you must make sure that you are communicating to the correct ShareBase instance. For instance, if your deployment is hosted in Mexico, you would use the base URL for Mexico. If it is hosted in the United States, you would use the base URL for the United States, and so on.

All of the ShareBase data centers now require TLS 1.2. You must use TLS 1.2 connections when communicating with the ShareBase API.

For example, in C# you would use the following line of code to enable TLS 1.2 handshakes:

ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Additional information on what TLS 1.2 is, how it helps to keep your content secure, and how to enable it can be found through official documentation from Microsoft: How to enable TLS 1.2.

Authorizing requests

Requests are authorized via an authorization token.

Site admins can create API tokens in the admin website. Once you have successfully obtained an authorization token, you can use it in subsequent requests. This is done by setting the Authorization header on each request to the API. API tokens do not expire, thus you will not need to obtain a new API token once one is obtained from your site admin.

For example, assume a site admin created an authorization token like Bearer f247ee44c22d1b597d963045b8c19092. Then, in a request to retrieve libraries, you would use the Bearer API token as follows:

GET /api/libraries
Authorization: Bearer f247ee44c22d1b597d963045b8c19092

Object notation

All data that is returned via the API other than document content is returned as JSON notation. So arrays are enclosed in [] and objects are enclosed in {}. An example of an array of cars would look something like:

[
    {
        "Make" : "Chrysler",
        "Model" : "LeBaron",
        "Year" : "1995"
    },
    {
        "Make" : "Nissan",
        "Model" : "GTR",
        "Year" : "2015"
    }
]

Links property

Some objects may contain a Links property. This property is an object that contains one or more links that can be followed via the API. The links are URLs to shortcuts for additional resources on that object. Where available, the application should make use of the links rather than composing the path to the resource. For example, a document contains a link to its content. While the caller could compose the link by hand, it is a best practice to use the link provided in the document object.

    {
        "DocumentId" : 123456,
        "DocumentName" : "Claim Photo for Policy 22344",
        "Links" : {
            "Content" : "https://app.sharebase.com/sharebaseapi/api/documents/123456/content"
        }
    }

var content = doc.Links.Content;
xhttp.open("GET",doc.Links.Content);

As opposed to:

var content = "https://app.sharebase.com/sharebaseapi/api/documents/" + 123456 + "/content";
xhttp.open("GET",content);

Embedded property

Some objects may contain an Embedded property. This property is an object that can contain one or more objects or an array of additional objects. In the following example, the car object contains a list of embedded Options on the vehicle.

{
    {
        "Make" : "Chrysler",
        "Model" : "Lebaron",
        "Year" : 1995,
        "Embedded" : {
            "Options" : {
                "Stereo" : "true",
                "Air" : "false",
                "HeatedSeats" : "false"
            }
        }
    }
}

Errors

ShareBase returns HTTP status codes as errors. Errors may also contain additional information in the body of the response.

There are a number of general errors that can be returned.

• 401 Unauthorized: This error typically occurs when the authorization token associated with the request has expired. A new authorization token must be obtained and the request resubmitted.

• 403 Forbidden: This error typically occurs when an authenticated user attempts to make a request to a resource they do not have rights to access.

• 500 Internal Server Error: This is a general error indicating that an error has occurred on the server. This may result from a malformed request or a defect in the server. These errors are logged on the server and reported to a ShareBase administrator for potential resolution.

Where appropriate, the API documentation will provide additional errors returned specifically by a given API.

Errors are often formatted as a single line in response bodies. In some cases, errors are returned in detailed ProblemDetail objects, like the following example:

{
    "status": 400,
    "type": "/validation_error",
    "title": "The request parameters did not validate.",
    "instance": "api/folders/1/share",
    "errors": [
        {
            "type": "/invalid_parameter",
            "title": "Invalid Parameter",
            "instance": "/AllowView&AllowDownload&AllowUpload",
            "detail": "At least one of the three values must be true."
        }
    ]
}