Created
April 17, 2020 21:15
-
-
Save radixdev/ce4cf8845bcb1c0b12c9750d29877658 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.3 | |
info: | |
version: '3.0' | |
title: 'V3' | |
description: | | |
Request Timing | |
When methods on the SDK are called, it should generally enqueue data locally into offline storage, and make batched flushes to the above endpoints on a timed basis, or when explicitly requested by the user. In general, the default flush interval should be in the 10s of seconds (reasonable default may depend on the nature of the platform), and should be configurable. | |
In the case of request failure (any non-20x response), the SDK should re-enqueue any failed events or attributes into local offline storage, and should begin an exponential slowdown of the flush interval, until a successful response is received. The backoff function should follow the decorrelated jitter algorithm below: | |
``` | |
sleep = min(5_minutes, random_between(normal_flush_interval, previous_sleep_time * 3)) | |
``` | |
App Version Code | |
See App Version Filter Functionality Improvement for the original design document. This field is the machine-parsable equivalent to `app_version`. This value incorporates the basic principles from https://semver.org/ but is extended for our needs to a fourth field, REVISION. Thus, this value is to be interpreted as `MAJOR.MINOR.PATCH.REVISION`. Missing values for any of the four aforementioned fields should be interpreted as 0. For example, "11.20.3" would correlate to MAJOR-11 MINOR-20 PATCH-3 REVISION-0. | |
HTTP Headers | |
All HTTP calls should include the following HTTP Header: | |
`X-Braze-Api-Key:API` key for the app | |
Based on the respond_with object, additional HTTP Headers should be added to the request. This allows DevOps to load balance the API calls based on what they are requesting. | |
If respond_with contains more than just config, such as including feed or triggers, include the following HTTP header: | |
`X-Braze-DataRequest:true` | |
If respond_with includes feed, also include the following HTTP header: | |
`X-Braze-FeedRequest:true` | |
If respond_with includes triggers, also include the following HTTP header: | |
`X-Braze-TriggersRequest:true` | |
contact: | |
name: PlatformName | |
email: platform@braze.com | |
servers: | |
- url: http://localhost:{port}/api/v3 | |
description: Local dev server | |
variables: | |
port: | |
default: 8080 | |
- url: https://sondheim.appboy.com/api/v3/data | |
description: Staging server | |
- url: https://dev.appboy.com/api/v3/data | |
description: Production server | |
paths: | |
/: | |
post: | |
parameters: | |
- in: header | |
name: X-Braze-Api-Key | |
description: API key for the app | |
type: string | |
required: true | |
- in: header | |
name: X-Braze-DataRequest | |
description: Include if respond_with contains more than just config, such as including feed or triggers | |
type: string | |
- in: header | |
name: X-Braze-FeedRequest | |
description: Include if respond_with includes feed | |
type: string | |
- in: header | |
name: X-Braze-TriggersRequest | |
description: Include if respond_with includes triggers | |
type: string | |
summary: test | |
requestBody: | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Root' | |
required: true | |
# headers: | |
# X-Rate-Limit: | |
# description: calls per hour allowed by the user | |
# schema: | |
# type: integer | |
# format: int32 | |
# X-Expires-After: | |
# description: date in UTC when token expires | |
# schema: | |
# type: string | |
# format: date-time | |
components: | |
schemas: | |
Root: | |
type: "object" | |
properties: | |
api_key: | |
description: API key for requesting App | |
type: "string" | |
required: true | |
device_id: | |
description: device identifier for requester | |
type: "string" | |
required: true | |
time: | |
description: UNIX timestamp of request initiation | |
type: "integer" | |
required: true | |
sdk_version: | |
description: | | |
Braze SDK version. Must conform to regex: `/\A(\d+\.?){1,4}\z/` | |
type: "string" | |
required: true | |
app_version_code: | |
description: | | |
The machine-readable build version of the host app. Must consist solely of 4 numbers and periods in accordance with the regex `/\A(\d+\.){3}(\d+)\z/` e.g. 1.2.3.4. | |
See App Version Filter Functionality Improvement for the original design document. This field is the machine-parsable equivalent to `app_version`. This value incorporates the basic principles from https://semver.org/ but is extended for our needs to a fourth field, REVISION. Thus, this value is to be interpreted as `MAJOR.MINOR.PATCH.REVISION`. Missing values for any of the four aforementioned fields should be interpreted as 0. For example, "11.20.3" would correlate to MAJOR-11 MINOR-20 PATCH-3 REVISION-0. | |
type: "string" | |
app_version: | |
description: version of the host app | |
type: "string" | |
device: | |
description: information about the device | |
type: "object" | |
events: | |
description: events to record for their respective users | |
type: "array" | |
items: | |
type: "string" | |
attributes: | |
description: attributes to set for their respective users | |
type: "array" | |
items: | |
type: "string" | |
feedback: | |
description: feedback items to submit. (Deprecated) | |
type: "array" | |
items: | |
type: "string" | |
respond_with: | |
description: data requested in response | |
type: "object" | |
sdk_flavor: | |
description: The type of SDK making the request. Note that "wordpress" is web only | |
type: "string" | |
enum: | |
- "unity" | |
- "react" | |
- "cordova" | |
- "xamarin" | |
- "segment" | |
- "mparticle" | |
- "flutter" | |
- "wordpress" | |
- "amp" | |
- "tealium" | |
test_user_data: | |
description: Test user data objects, such as device logs. Expects only 1 TestUserDataObject per user-id | |
type: "array" | |
items: | |
type: "string" |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment