Guide
Below are a list of the HTTP endpoints expected in an integration application.
Required
GET /: returns app information
POST /validate: performs validation of the account
POST /api/v1/synchronizer/config: returns synchronizer configuration
POST /api/v1/synchronizer/schema: returns synchronizer schema
POST /api/v1/synchronizer/data: returns data
Optional
GET /logo: returns an image/svg+xml representation of the application's logo
POST /api/v1/synchronizer/datalist: returns possible options for filter fields
POST /api/v1/synchronizer/filter/validate: performs filter fields validation
POST /api/v1/synchronizer/resource: returns files those behind security wall
POST /api/v1/synchronizer/webhooks: setting up webhook
POST /api/v1/synchronizer/webhooks/pre-process: verify and process incoming event
POST /api/v1/synchronizer/webhooks/transform: convert event payload into data that can be handled by Fibery
GET /
GET "/" endpoint is the main one which returns information about the app. You can find response structure in Custom App: Domain.
Response example:
{
"version": "1.0", // string representing the version of your app
"name": "My Super Application", // title of the app
"description": "All your base are belong to us!", // long description
"authentication": [], // list of possible account authentication approaches
"sources": [], // empty error
"responsibleFor": { // app responsibility
"dataSynchronization": true // indicates that app is responsible for data synchronization
}
}
Authentication Information
The authentication object includes all account schema information. It informs the Fibery front-end how to build forms for the end-user to provide required account information. This property is required, even if your application does not require authentication. At least one authentication object must be provided within array.
In case when application doesn't require authentication, the fields array must be omitted.
Important note: if your app provides OAuth capabilities for authentication, the authentication identifiers must be oauth and oauth2 for OAuth v1 and OAuth v2, respectively.
Only one authentication type per OAuth version is currently supported.
{
"authentication": [
{
"id": "basic", // identifier
"name": "Basic Authentication", // user-friendly title
"description": "Just using a username and password", // description
"fields": [ //list of fields to be filled
{
"id": "username", //field identifier
"title": "Username", //friendly name
"description": "Your username, duh!", //description
"type": "text", //field type (text, password, number, etc.)
"optional": true, // is this a optional field?
},
/* ... */
]
}
]
}
POST /validate
This endpoint performs account validation when setting up an account for the app and before any actions that uses the account. The incoming payload includes information about the account type to be validated and all fields required:
If the account is valid, the app should return HTTP status 200 with a JSON object containing a friendly name for the account:
Incoming body:
{
"id": "basic", // identifier for the account type
"fields": { //list of field values to validate according to schema
"username": "test_user",
"password": "test$user!",
/*...*/
}
}
Success Response:
{"name": "Awesome Account"}
If the account is invalid, the app should return HTTP status 401 (Not Authorized) with a simple JSON object containing an error message:
Failure Response:
{"message": "Your password is incorrect!"}
Refresh Access Token
In addition this step can be used as a possibility to refresh access token. The incoming payload includes refresh and access token, also it can include expiration datetime. Response should include new access token to override expired one.
Refresh Access Token Request:
{
"id": "oauth2",
"fields": {
"access_token": "xxxx",
"refresh_token": "yyyy",
"expire_on": "2018-01-01"
}
}
Response sample after token refresh:
{
"name": "Awesome account",
"access_token": "new-access-token",
"expire_on": "2020-01-01"
}
POST /api/v1/synchronizer/config
The endpoint returns information about synchronization possibilities based on input parameters. It instructs Fibery about:
Request
All input parameters are optional.
Name | Type | Description |
|---|
account | object | selected account's fields |
Request example:
{
"account": {
"token": "user-token"
}
}
Response
Response example:
{
"types:": [
{"id": "bug", "name": "Bug"},
{"id": "us", "name": "User Story"},
],
"filters": [
{
"id": "modifiedAfter",
"title": "Modified After",
"optional": true,
"type": "datebox"
}
]
}
Output parameters:
Name | Type | Description |
|---|
types | [{id: string, name: string}]
| supported types list with id and display name |
filters | Array of filters | it is used to help the user to exclude non-required data. |
webhooks | {enabled: true, type: 'ui'}
| Optional fields that indicates that webhook functionality is supported |
Filter information
The filter object is used to help the user to exclude non-required data. Just like other field-like objects, the filter object is not required. If nothing is provided, users will not be able to filter out data received from the app.
For more information about filters, please refer to Custom App: Domain and Custom App: Fields
POST /api/v1/synchronizer/schema
Integration app must provide data schema in advance so Fibery will be able to create approriate types and relations and then be able to maintain them.
It should provide a schema for all requested types. Each type must contain name and id field. In additional there is a reserved field __syncAction that should be added to the schema if delta synchronization with possibility of removing items should be supported.
Request
Request contains:
types - an array of selected type ids
filter - currently configured filter
account - selected account
Request example
{
"types": ["pullrequest", "repository"],
"filter": {
"owner": "fibery",
"repositories": ["fibery/core", "fibery/ui"]
},
"account": {
"token": "token"
}
}
Response
Includes schema for all requested types
Schema is JSON object where key is field and value if field description. Field description contains:
field | description | type |
|---|
id | Field id | string |
ignore | Is field visible in fields catalog | boolean |
name | Field name | string |
description | Field description | string |
readonly | Disable modify field name and type | boolean |
type | Type of field | "id", "text" ,"number" , "date", "array[text]" Learn more in Integration Schema types |
relation | Relation between types | see relations section |
subType | Optional Fibery sub type | "url" , "integer", "email", "boolean","html", "md", "files", "date-range" Learn more in Integration Schema types |
Response example:
{
"repository": {
"id": {
"type": "id",
"name": "Id"
},
"name": {
"type": "text",
"name": "Name"
},
"url": {
"type": "text",
"name": "Original URL",
"subType": "url"
}
},
"pullrequest": {
"id": {
"type": "id",
"name": "Id"
},
"name": {
"type": "text",
"name": "Name"
},
"repositoryId": {
"type": "text",
"name": "Repository Id",
"relation": {
"cardinality": "many-to-one",
"name": "Repository",
"targetName": "Pull Requests",
"targetType": "repository",
"targetFieldId": "id"
}
},
"__syncAction": {
"type": "text",
"name": "Sync Action"
}
}
}
Relations
relation field provides a possibility to create a relation between entities in Fibery. It contains following fields:
field | description | type |
|---|
cardinality | Type of relation | "many-to-one", "many-to-many", "one-to-one" |
name | Name of the field on source side | string |
targetType | Id of target type | string |
targetName | Field name of target side | string |
targetFieldId | Find relation by value from field | string |
Repository will have following fields (example includes only relation fields):
Pull Request will have following fields:
Example:
{
"repository": {
"id": {
"type": "id",
"name": "Id"
},
"name": {
"type": "text",
"name": "Name"
},
"url": {
"type": "text",
"name": "Original URL",
"subType": "url"
}
},
"pullrequest": {
"id": {
"type": "id",
"name": "Id"
},
"name": {
"type": "text",
"name": "Name"
},
"repositoryId": {
"type": "text",
"name": "Repository Id",
"relation": {
"cardinality": "many-to-one",
"name": "Repository",
"targetName": "Pull Requests",
"targetType": "repository",
"targetFieldId": "id"
}
}
}
}
Reserved field - __syncAction
Sync action is reserved field that won't be visible for end user. The field is used for delta synchronization when entity should be deleted.
POST /api/v1/synchronizer/data
Data endpoint performs actual data retrieving for the specified integration settings. Data retrieving is run by each type independently.
Data synchronization supports:
pagination
delta synchronization
Request
Inbound payload includes following information:
types - array of selected type ids
requestedType - currently fetching type
account - account on behalf of data should be fetched
filter - currently configured filters
lastSynchronizedAt - OPTIONAL field that indicated when last successful synchronization was run
pagination - OPTIONAL field includes pagination settings that was returned from previous data request
schema - current integration schema
Request example:
{
"requestedType": "pullrequest",
"types": ["repository", "pullrequest"],
"filter": {
"owner": "fibery",
"repositories": ["fibery/core", "fibery/ui", "fibery/apps-gallery"]
},
"account": {
"token": "token"
},
"pagination": {
"repositories": ["fibery/ui", "fibery/apps-gallery"]
},
"lastSynchronizedAt": "2020-09-30T09:08:47.074Z"
"schema": {
"repository": {
"id": {
"name": "Id",
"type": "text"
}
}
}
}
Response
Outboud payload includes:
items - REQUIRED array of fetched data rows
pagination - OPTIONAL parameter that includes information about pagination
synchronizationType - OPTIONAL parameter with possible values delta or full. It indicates how data will be handled on Fibery side. If delta is set then only provided changes will be applied. Fibery will be looking for __syncAction field to identify whether row should be set or removed. If __syncAction equal REMOVE then corresponding entity will be removed. If full is set then unsynced data will be removed (if keep unsynced is unchecked).
Response example:
{
"items": [
{
"id": "PR_1231",
"name": "Improve performance"
},
{
"id": "PR_1232",
"name": "Fix bugs"
}
],
"pagination": {
"hasNext": true,
"nextPageConfig": {
"repositories": ["fibery/apps-gallery"]
}
},
"synchronizationType": "full"
}
Errors
If something goes wrong then integration app should respond with corresponding error HTTP status code and error message.
Sample of error about sync failure:
{
"message": "Unable to fetch data."
}
But some errors can be fixed if try to fetch data later. In this case error body should include tryLater flag with value true. Fibery will retry this particular page later on.
Sample of error about limits
{
"message": "Rate limits reached",
"tryLater": true
}
GET /logo
OPTIONAL
The /logo endpoint is used to provide a SVG representation of a connected application's logo. This endpoint is entirely optional. Valid responses are a HTTP 200 response with a image/svg+xml content type, a HTTP 204 (No Content) response if there is no logo, or a 302 redirect to another URI containing the logo. If no logo is provided, or an error occurs, the application will be represented with our default app logo.
POST /api/v1/synchronizer/datalist
OPTIONAL
Request
The inbound payload includes:
types - an array of selected type ids
account - selected account
field - name of requested field
dependsOn - object that contains filter key-value pairs of dependant fields
Request body:
{
"types": ["pullrequest", "branch"],
"account": {
"token": "token"
},
"field": "repository",
"dependsOn": {
"owner": "fibery"
}
}
This endpoint performs retrieving datalists from filter fields that marked with datalist flag.
Response
The response from your API should include items that is a JSON-serialized list of name-value objects: The title in each object is what is displayed to the end-user for each value in a combobox and the value is what is stored with the filter and what will be passed with subsequent requests that utilize the user-created filter.
Response sample:
{
"items": [
{
"title": "fibery/ui",
"value": "124"
},
{
"title": "fibery/core",
"value": "125"
}
]
}
POST /api/v1/synchronizer/filter/validate
OPTIONAL
This endpoint performs filter validation. It can be useful when app doesn't know about what filter value looks like. For example, if your app receives sql query as filter you may want to check is that query is valid.
Request
Request body contains:
types - array of selected type ids
account - account on behalf of data should be fetched
filter - currently configured filters
Request example:
{
"types": ["repository", "pullrequest"],
"filter": {
"owner": "fibery",
"repositories": ["fibery/core", "fibery/ui", "fibery/apps-gallery"]
},
"account": {
"token": "token"
}
}
Response
If the filter is valid, the app should return HTTP status 200 or 204.
If the account is invalid, the app should return HTTP status 400 (Bad request) with a simple JSON object containing an error message:
Error response sample:
{"message": "Your filter is incorrect!"}
POST /api/v1/synchronizer/resource
OPTIONAL
This endpoint is used to access files that require authentication. For example, if the schema contains a files field and the files are not accessible by direct link then this route can be used to download files by specifying a url as app://resource?url=:url&value=1. As a result the route will be called with url and value params. The resource endpoint is called with all query parameters specified in app://resource url.
Request
Request body contains:
types - array of selected type ids
account - account on behalf of data should be fetched
filter - currently configured filters
params - list of parameters.
Response
File content as a stream
POST /api/v1/synchronizer/webhooks
OPTIONAL
The endpoint is responsible for installing, updating or reinstalling a webhook based on provided parameters. It's the place where webhook based configuration starts.
Request. It accepts following parameters:
types - an array of selected types ids
filter - currently configured filter
account - authenticated external account
webhook - OPTIONAL. If it's null then a new webhook is going to be installed, otherwise it will contain current webhook configuration (that is returned by THIS endpoint)
{
"types": ["pullrequest", "repository"],
"filter": {
"owner": "fibery",
"repositories": ["fibery/ui", "fibery/core"]
},
"account": {
"token": "token"
},
"webhook": null
}
Response:
Response is a JSON object with following required fields
id - some random id
workspaceId - 3rd party workspace id linked to webhook/synchronization (e.g. slack workspace, intercom workspace, gitlab organization)
any other data that you want to receive on reinstall event.
{
"id": "webhook_id",
"workspaceId": "workspaceId",
"events": ["create_repo", "delete_repo"]
}
POST /api/v1/synchronizer/webhooks/pre-process
OPTIONAL
The route is responsible for initial pre processing of request. Data that is received by this route is the same as 3rd party service sends without any changes (almost). It's done to be able to calculate request signature properly.
Goals of the service:
verify incoming request (usually it means that service should verify signature based on 3rd party system chosen algorithm, e.g. hubspot webhook verification)
response with data that should be sent to 3rd party caller and list of workspace ids this event will work for. HTTP status code of the response will also be forwarded to 3rd party system
Request
Request payload and headers depends on 3rd party service
Response
Response should include following fields:
{
"reply": {
"challenge": "value"
},
"workspaceIds": ["team-a", "team-b"]
}
POST /api/v1/synchronizer/webhooks/transform
OPTIONAL
This route is responsible for converting event payload into data that can be handled by Fibery. Data is applied by delta synchronization rules.
Request
Request payload includes:
params - event headers that comes from external system.
payload - event body that comes from external system.
types - an array of selected type ids
filter - currently configured filter
account - selected account
{
"params": {
"x-github-id": "1234",
"x-github-signature256": "dsadsa"
},
"payload": {
"action": "create",
"repository": {
"id": "repo1"
}
},
"types": ["pullrequest", "repository", "branch"],
"filter": {
"owner": "fibery",
"repositories": []
},
"account": {
"token": "token"
}
}
Response
Response includes data object that is a map of data arrays by type id.
{
"data": {
"repositories": [
{
"id": "repo1",
"name": "Repo1",
"__syncAction": "SET"
}
],
"branches": [
{
"id": "master",
"name": "master",
"repositoryId": "repo1",
"__syncAction": "SET"
}
]
}
}