Getting Remote Configs via REST API

Joystick manages all of your remote configs in one powerful platform, and allows you to retrieve it easily over REST API at scale.

API Keys

You will need to create an API Key to retrieve content via API.

Request and Response

This is the request and response for getting a single piece of content via REST API. You can get also get multiple pieces of content with a single call.

Request

End Point

POST https://api.getjoystick.com/api/v1/config/:contentId/dynamic

Replace the :contentId indicated with the Configuration Content Id you created. :contentId is not case sensitive.

Header	Value	Required	Notes
`Content-Type`	application/json	Yes
`X-Api-Key`	Your API Key	Yes	The API key created for the environment you are targeting. This is different for each environment.

Request Query Parameters

Query Param	Requirement	Description
`responseType`	Optional	Case sensitive. Indicates to serialize the 'data' object on the response. See the response section for the output. Usage: `/config/:contentId/dynamic?responseType=serialized`

Request Body

The request body should be JSON, and cannot be empty. It must at minimum consist of the following snippet.

Request Body Example - Minimum RequirementRequest Body Example - Extended

{
    "u": "",
    "p": {}
}

{
    "u": "the-unique-user-id",
    "v": "3.2.1",
    "p": {
        "level": 1,
        "location": "north_pole",
        "balance": 101,
        "days_since_install": 14
    }
}

Attribute	Requirement	Description
`u`	String. Required.	This is the unique identifier for a particular user. We use this identifier to split users into sticky AB Test groups. Send an empty string at minimum.
`p`	Object. Required.	This is a dictionary of key:value attributes that can be used by Joystick for segmentation (different config content can be returned based on the attributes you send). Send an empty object at minimum. View Usage Details
`v`	String. Optional.	This is the semantic version of your app that is making the request. We highly recommend sending this as we are able to deliver backward compatible revisions of configuration based on semantic versioning. This must be a three-part semantic version as string e.g. "3.2.1"

Example

curl --location --request POST 'https://api.getjoystick.com/api/v1/config/:contentId/dynamic' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{"u": "", "p": {}}'

You should get back the content you have stored in Joystick.

Troubleshooting

Having issues? View our troubleshooting guide.

Response

Default ResponseResponse with Data SerializedResponse Config Only

// This is the default response with your config in the "data" wrapper.
{
  "data":
  {
    "greeting": "Hello, world!"
  },
  "hash": "2277e0d4",
  "meta":
  {
    "uid": 0, "mod": 0, "seg":[]
  }
}

// You can get your config serialized by adding the query param ?responseType=serialized
{
  "data": "{ \"greeting\": \"Hello, world!\"}",
  "hash": "2277e0d4",
  "meta":
  {
    "uid": 0, "mod": 0, "seg":[]
  }
}

// Receive just your config content without the "data" wrapper by
// removing the trailing /dynamic from the request endpoint.
{
    "greeting": "Hello, world!"
}

Response Attribute	Description
`data`	This is your configuration content returned as well formatted JSON with a) all in-line comments stripped out and b) any dynamic content replaced based on segmentation or ab-testing. This can optionally be returned as a serialized string.
`hash`	This is a hash of the content. You can use this to determine if the content has been updated since your last request. The hash only changes if the content has changed. For example, if on a request you get the same hash, you may not need to updated the cached version of the configuration content in your app.
`meta.uid`	Joystick we take the put the `u` parameter you send on the request through a hashing function and generate a stable integer user id (the same "u" string that you send in will always generate the same integer. This is returned for your reference. The use of this integer is to place your users into stable ab-test groups by using modulo 1000.
`meta.mod`	The last three digits of the `meta.uid`. This will help you determine which AB test group the user has been assigned to.
`meta.seg`	This is an array of objects that will tell you the segment name and ab test group variant name that mutated the data in this request. If it is empty, it means the response is default values, and not in any AB test or segmentation. Learn more about this in Dynamic Content.

Understanding the "meta.seg" component

The meta.seg component of the response is important for Business Intelligence or Analytics. It will tell you the segment name, variant name and an optional small snippet of additional information you can pass.

Sample Response with meta.seg

{
    "data": {...},
    "hash": "2277e0d4",
    "meta": {
        "uid": 0,
        "mod": 0,
        "seg": [
        {
            "n": "My Test",
            "v": "Variant A",
            "i": "Optional Information"
        },
        {
            "n": "My Segment",
            "v": null, // v is null if there was only segment details provided.
            "i": "More Optional Information"
        }
        ]
    }
}

seg object part	Description
`n`	Name of the segment that the response was included in.
`v`	Variant Name. If you are running an AB Test using Joystick, this will the name or label of the variant that the response was included in.
`i`	This is optional information you can to send to tag or identify a particular variant. This can be configured on the Dynamic Mapping.

Additional Information

We highly recommend there is a fallback in your app to gracefully handle the case if Joystick cannot be reached. Please refer to our Integration Guide for more information!

You can get multiple configs back with one call. Please refer to our Multiple Content API!