# Introduction

The JourneyApps API allows you to integrate or "sync" your own databases or systems with your JourneyApps application. In other words, it allows you to connect one of your own systems to your app in a way that the two can "talk" to each other behind the scenes.

On a technical level, the API takes the form of an HTTP [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) API, and uses standard HTTP authentication.

### Enabling the API

The API is configured on an *App Deployment* level, which means that each deployment of your app (you can see each deployment listed in the Deployments workspace or panel in OXIDE) has its own API credentials.

To obtain the API credentials for a specific *App Deployment*:

1. Open the deployment in the Data Browser
2. Open the dropdown in the top right corner, and click on *Manage API*. If this option is not immediately visible, you may need to elevate your permissions.

On the Manage API page, you'll be able to see the deployment's HTTP Basic Username and Password or create *Named Tokens*. Please keep this information private and record it in a secure place.

### Authentication

API authentication uses either a *Named Token* specified in the HTTP `Authorization` header, or using [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication).

The syntax for the *Named Token* header is `Authorization: Bearer O:mytokenhere`.

All API requests must occur over HTTPS and each request must include authentication credentials.

### HTTP Endpoints

An endpoint is the base URL that you connect to when using the API. 

These base URLs are dynamic for each of your app's deployments, and can be reviewed on the *Manage API* data browser page for your deployment (see steps to access this page in the [Enabling the API](#enabling-the-api) section above).

Base URLs have the following structure:

{% tabs %}
{% tab title="Current structure" %}
For deployments created after 31 January 2023, the following structure applies:

`https://{app-deployment-id}.backend.{region-code}.journeyapps.com/api/v4/{backend-deployment-id}`

{% hint style="info" %}
**Deployment IDs**

Note that deployments are identified by different IDs in the app (OXIDE), backend and CloudCode. The Backend API typically uses the backend deployment ID.
{% endhint %}

#### Example: 

`https://62d541f4156bc4dd685318da.backend.us.journeyapps.com/api/v4/62d541ff9f54b7000706c585`
{% endtab %}

{% tab title="Legacy structure" %}
For deployments created before 31 January 2023, the legacy structure applies:

`https://run{deployment-environment-and-region-code}.journeyapps.com/api/v4/{backend-deployment-id}`

#### Examples: 

Testing environment:

`https://run-testing-us.journeyapps.com/api/v4/615ae1ee8c5ef500078a4908`

Production environment:

`https://run-us.journeyapps.com/api/v4/615ae1ee8c5ef500078a4908`

In this legacy structure, the `{deployment-environment-and-region-code}` placeholder of the base URL is constructed per deployment region and environment as follows:

<table><thead><tr><th width="173.68167202572346">Region</th><th width="150">Environment</th><th>Base URL snippet</th></tr></thead><tbody><tr><td>United States</td><td>Testing</td><td><code>https://run-testing-us.journeyapps.com</code></td></tr><tr><td></td><td>Staging</td><td><code>https://run-staging-us.journeyapps.com</code></td></tr><tr><td></td><td>Production</td><td><code>https://run-us.journeyapps.com</code></td></tr><tr><td>Europe</td><td>Testing</td><td><code>https://run-testing-eu.journeyapps.com</code></td></tr><tr><td></td><td>Staging</td><td><code>https://run-staging-eu.journeyapps.com</code></td></tr><tr><td></td><td>Production</td><td><code>https://run-eu.journeyapps.com</code></td></tr><tr><td>Australia</td><td>Testing</td><td><code>https://run-testing-au.journeyapps.com</code></td></tr><tr><td></td><td>Staging</td><td><code>https://run-staging-au.journeyapps.com</code></td></tr><tr><td></td><td>Production</td><td><code>https://run-au.journeyapps.com</code></td></tr><tr><td>South Africa (Deprecated)</td><td>Testing</td><td><code>https://run-testing.journeyapps.com</code></td></tr><tr><td></td><td>Staging</td><td><code>https://run-staging.journeyapps.com</code></td></tr><tr><td></td><td>Production</td><td><code>https://run.journeyapps.com</code></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Base URL and Relative URL**

Throughout the rest of the documentation, we will indicate the URL that you need to use relative to the base URL to perform a particular function (e.g. [Retrieve all Objects](https://docs.journeyapps.com/reference/backend-api/api-reference/retrieve-all-objects), [Create a New Object](https://docs.journeyapps.com/reference/backend-api/api-reference/create-a-new-object), [Update a Single Object](https://docs.journeyapps.com/reference/backend-api/api-reference/update-a-single-object), etc).

For example, in the [Create a New Object](https://docs.journeyapps.com/reference/backend-api/api-reference/create-a-new-object) section, we indicate that you need to send an HTTP POST request to the relative URL `/api/v4/`*`backend-deployment-id`*`/objects/`*`model`*`.json`&#x20;

In order to create an object. In other words, let's say your deployment's backend ID is `54c89f71923a3be4fe00000f` and you want to create a new 'car' object in in this deployment (which is in the United States region), you'll send an HTTP request to:

`https://62d541f4156bc4dd685318da.backend.us.journeyapps.com/api/v4/54c89f71923a3be4fe00000f/objects/car.json`&#x20;
{% endhint %}

### Request Parameter Formats

Parameters supplied to API functions may be in any of the following formats. It may be necessary to set the Content-Type HTTP header as shown.

<table><thead><tr><th width="182.33333333333331">Format</th><th>Content-Type Header</th><th>Example</th></tr></thead><tbody><tr><td><a href="http://en.wikipedia.org/wiki/JSON">JSON</a></td><td><code>application/json</code></td><td><code>{"client":{"address":"123 South"}}</code></td></tr><tr><td><a href="http://en.wikipedia.org/wiki/Percent-encoding">URL-encoded</a> key-value pairs</td><td><p><code>application/x-www-form-urlencoded</code></p><p><em>This is the default for POST requests and usually does not have to be specified explicitly.</em></p></td><td><code>client[address]=123%20South</code></td></tr></tbody></table>

#### How do I format fields?

For details on how to format the object fields that you send to the API, please see the [Field Representation](https://docs.journeyapps.com/reference/backend-api/api-reference/field-representation) section:

{% content-ref url="api-reference/field-representation" %}
[field-representation](https://docs.journeyapps.com/reference/backend-api/api-reference/field-representation)
{% endcontent-ref %}

### Response Data Formats

All v4 API responses are in currently in JSON. It is however still recommended that you indicate the acceptance of JSON by either:

* Setting the Accept HTTP header to `application/json`
* By appending `.json` to the end of the URL. For example: `BASE-URL/api/v4/backend-deployment-id/objects/assets.json`. Note: See the section about [HTTP Endpoints](#http-endpoints) above to get the value for the BASE-URL placeholder.

#### In what format will my fields be returned?

For details on how your object fields received from the API will be formatted, please see the [Field Representation](https://docs.journeyapps.com/reference/backend-api/api-reference/field-representation) section.

{% content-ref url="api-reference/field-representation" %}
[field-representation](https://docs.journeyapps.com/reference/backend-api/api-reference/field-representation)
{% endcontent-ref %}

### Error Handling

#### Response Codes

The API uses standard HTTP status codes to indicate the outcome of an API request.

* A status code in the `2xx` range indicates that the operation has completed successfully.
* A status code in the `3xx` range indicates a redirect. This is only used for specific calls, for example for fetching attachments.
* Any other status code indicates that the operation has failed:
* A status code in the 4xx range indicates that invalid input from your side is responsible for the error.
* A status code in the 5xx range indicates that an internal server error on the JourneyApps side is responsible for the error.

Full details on error responses are described on the [Error Responses](https://docs.journeyapps.com/reference/backend-api/api-reference/error-responses) page:

{% content-ref url="api-reference/error-responses" %}
[error-responses](https://docs.journeyapps.com/reference/backend-api/api-reference/error-responses)
{% endcontent-ref %}

### API Stability

No breaking changes will be made to an existing stable API version. If we do need to make a breaking change, we will do one of:

1. Publish it as part of a new API version, e.g. API v5.
2. Place it behind a feature flag, that is enabled on request for specific apps.
3. Give sufficient notice in the rare case that a change to an existing API cannot be avoided.

Note that we will periodically add new API calls to an existing API version, as well as new fields or HTTP headers to API responses. This is not considered a breaking change, and API clients **must ignore any unrecognized fields**.

Removing, renaming or changing the type or behavior of an existing API call or field is considered a breaking change, and the above breaking change policy will apply.

{% hint style="warning" %}

#### Beta APIs

Certain APIs, such as the `api.journeyapps.com`, may be classified as "Beta". In this case, we may make breaking changes or even completely remove or replace the API, but will strive to give sufficient notice in such cases.
{% endhint %}

###