RPC APIs

RPC APIs

A vast majority of Bubblehouse APIs use the same calling convention:

• available over HTTP with a consistent URL scheme;
• JSON-based (accept and return JSON);
• RPC-style (function name in the URL).

We call these RPC APIs. Examples are:

1. Loyalty API
2. Loyalty Admin API
3. Order API
4. Triggers API

Non-RPC APIs

Some APIs are (slightly or very) different. We call them non-RPC APIs:

1. Blocks API (serves HTML content).
2. Hooks API (JSON-based HTTP API that you implement and we invoke on your servers).
3. Block Client API (client-side postMessage-based protocol for communication with embedded Bubblehouse Blocks).

Calling conventions for these APIs are described in the documentation of those APIs. However, other common sections still apply: versioning, authentication and rate limiting.

How to call RPC APIs

Post JSON data to https://app.bubblehouse.com/api/v<GLOBALVER>/<SHOP>/<FUNC><FUNCVER>.

• Use HTTP POST verb.
• Send JSON body.
• On success, the call returns HTTP 200 OK and a JSON response body.
• On error, the call returns HTTP 4xx or 5xx status and a JSON error response body (all error responses use the same format).

To make an authenticated call, pass Authorization: Bearer <token>, where <token> is the appropriate JWT token (either a shop token or a customer token).

Alternative: GET

For read-only calls, you can use HTTP GET verb instead. If you need to pass parameters, you will need to use alternative ways to send those, because you obviously cannot send a JSON body with a GET request.

We recommend that you always use POST. Support for GET is mainly a convenience for development and debugging purposes.

Alternative: application/x-www-form-urlencoded

Instead of a JSON body, you can pass simple parameters via URL-encoded form data. This is mainly a convenience for curl'ing during development and debugging.

Alternative: auth

Instead of Authorization: Bearer <token>, you can pass the token via auth query or URL-encoded form body param. This is mainly a convenience for development and debugging purposes, so that you can build and share fully-functional URLs for authenticated GET-based read-only requests.

Examples

Anonymous GET: https://app.bubblehouse.com/api/v2022021/shopify-lumin-beauty/Status1.

Anonymous curl:

curl -X POST -d '{}' https://app.bubblehouse.com/api/v2022021/shopify-lumin-beauty/Status1

Authenticated curl:

curl -X POST -d '{}' -H 'Authorization: Bearer <token>' https://app.bubblehouse.com/api/v2022021/shopify-lumin-beauty/Status1

Optional properties

Response properties marked as optional may be either omitted or set to null by Bubblehouse. You need to support both cases.

In the Hooks API, the same holds for the input data, and Bubblehouse with accept both null and missing properties in your hook responses.

Extra properties

Unlike most JSON APIs, Bubblehouse rejects any inputs that send unsupported property names. This is intended to protect you from typos going unnoticed.

We reserve the right to extend the list of properties that we return, however, so don't do the same on your end when talking to Bubblehouse.

Related topics