API Requests

Host

This page provides information on the HTTP requests to the API, including the URL structure, HTTP verbs and headers. It also outlines the concepts of External References, Pagination and GET parameter filters.

The host for Web API V3 requests is dependent on your tenant URL, which is the prefix before .bubbleppm.com in the URL you use to access the application. For example, if your tenant URL is https://demo.bubbleppm.com your API URL prefix will be https://demo.bubbleppm.com/api/v3/ Within this documentation we will substitute this part of the URL with <tenant> e.g. https://<tenant>.bubbleppm.com/api/v3/ .

Authorization Header

You must provide an authorization header as described in Authentication and Authorization.

HTTP Verbs

Per the RESTful API specification, our API supports the following HTTP verbs

Verb	Description
GET	Retrieve a resource or group of resources
POST	Create a new resource
PUT	Update an existing resource
DELETE	Delete an existing resource
OPTIONS	View allowed verbs against a specific resource

Accept Header

The API provides JSON responses. It doesn't currently require the accept header, but might in the future. If not set, the API will use application/json.

CODE

GET https://<tenant>.bubbleppm.com/api/v3/resources/ HTTP/1.1
Accept: application/json

Request body

When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

CODE

POST https://<tenant>.bubbleppm.com/api/v3/resources/ HTTP/1.1
Content-Type: application/json

CODE

{
  "name": "new name"
}

External References

The PPM API supports a feature that enables tenants to reference objects via an External Reference. This is a string value that can be used as a substitute for the internal primary key for the object in PPM.

External References are unique per Application/Object combination. Each application can only have one reference to each object in PPM, with the exception of Keywords, where these have a unique constraint within the Keyword Group they’re related to.

The string can be used in both the URL structure of HTTP requests, and within the body of payloads for POST and PATCH requests.

To make sure the API looks up an object via an External Reference rather than a Primary Key add a URL Query Param called `use_external_refs`

CODE

GET https://<tenant>.bubbleppm.com/api/v3/entities/<entity_external_ref>/?use_external_refs HTTP/1.1

Parameter	Description
use_external_refs	Flag to indicate External References should be used to look up an object

Some GET resources allow for retrieval of information in batches.

When requesting multiple items, we will default the request limit to 100 items. You can specify a different limit by updating the instance config value V3_MAX_PAGE_SIZE with the integer value you want the page size to be.

Pagination can be enabled on your instance by setting the instance config value PAGINATE_V3_RESPONSE to TRUE. The instance default is to not paginate responses.

Below is a basic pagination example.

CODE

GET https://<tenant>.bubbleppm.com/api/v3/resources/?page=2 HTTP/1.1

Parameter	Description
page	The page number to return

All paginated response will conform to the following output where the results key contains a list of the returned values as described by the resources documentation page. The last page in the set will have the nextPage key set to null

CODE

{
    "total": 5000,
    "nextPage": 2,
    "results": [...]
}

Search & Parameters

Some resources allow for you to search by a specific field. Other resources require you to append a parameter to the URI.

In this example, we will display a paginated URI example, searching for resources where the email contains foo.

CODE

GET https://<tenant>.bubbleppm.com/api/v3/resources/?email=foo&bar=baz HTTP/1.1

Successful Requests

Below is a general overview of what resource objects return with successful Web API requests.

Verb	Resource object returned
GET	Returns a single resource object or array of resource objects
PUT	Returns the updated resource object
DELETE	No content is returned
POST	Returns the newly created resource object