Introduction
FLOW API provides a set of endpoints to query data in the FLOW platform.
The api domain is formatted as follows:
https://{client}]-api-{environment}.brightsites.co.uk/
Flow instance will be provided by you FLOW account manager.
The options for environment are:
- dev
- uat
- prod
REST & WEB APIs
The Flow AIP is basically 2 different APIs merged into one.
There is a REST API that is used for most CRUD operations and a custom API for powering the WEB and some parts of the CMS apps.
The rest API provides endpoints for all the different entity types and the list of active endpoints for each of the clients can be found on the Web Services REST page in the API eg:
https://indy-api-dev.brightsites.co.uk/admin/config/services/rest
Viewing an entity via the rest API vs viewing it by the WEB API
To illustrate the differences in the APIs here is the same article via both APIs
// REST API
https://indy-api-dev.brightsites.co.uk/node/1000000?_format=json
// WEB API by path
https://indy-api-dev.brightsites.co.uk/api/independent.co.uk?path=/sport/football/news/james-lawton-aragones-won-over-lovers-of-the-game-with-sweet-blend-of-style-and-discipline-857682.html
// WEB API by ID
https://indy-api-dev.brightsites.co.uk/api/independent.co.uk?id=1000000
Reading and Writing using the REST API
The REST API has more parameters on it's output than are needed when updating an entity
There are also only a few field types, we reuse the same field types in multiple places to create different fields
Below are examples of the different field types and the differences between reading and writing to the field types
String/Int/Bool values
These basic value fields are recognisable as being an array with a single object that has a single property called value
You read from and write to these fields in the same way, by either reading the value or setting the value.
// Reading
"title": [{
"value": "James Lawton: Aragones won over lovers of the game with sweet blend of style and discipline"
}]
"field_commenting": [{
"value": true
}]
"field_priority": [{
"value": 4
}]
// Writing
"title": [{
"value": "James Lawton: Aragones won over lovers of the game with sweet blend of style and discipline"
}]
"field_commenting": [{
"value": true
}]
"field_priority": [{
"value": 4
}]
Reference fields
These reference fields are recognisable as being an array with a single o multiple objects that have a property called target_id
The API is made an interface to various types different entity types.
Each entity type also has bundles so an article for example is an entity type called node with a bundle called article.
We join these entities together by referencing one from the other, an example of this is the articles, they each reference multiple different Terms entities from different vocabularies.
The example below is referencing an Article Type Term from the Article, there is a field on the article which stores the reference to the term in question.
The only 2 properties that should be sent when creating or updating these references is the target_id & target_type, the other properties should not be sent back to the API when updating.
// Reading
"field_article_type": [{
"target_id": 13,
"target_type": "taxonomy_term",
"target_uuid": "4e6f1ccc-c0a9-498f-aeca-5bcadd14ec15",
"url": "/article-type/news",
"pwamp": {
"name": "News",
"path": "/article-type/news",
"id": "13",
"uuid": "4e6f1ccc-c0a9-498f-aeca-5bcadd14ec15",
"changed": "1595340845",
"firstLetter": "n"
}
}]
// Writing
"field_article_type": [{
"target_id": 13,
"target_type": "taxonomy_term",
}]
Timestamp fields
These are one of the oddest field types, when viewing the data it is formatted as a human-readable date but when updating you have to send the UNIX timestamp value
// Reading
"field_article_display_date": [{
"value": "2020-10-12T22:55:01+00:00",
"format": "Y-m-d\\TH:i:sP"
}]
// Writing
"field_article_display_date": [{
"value": 1602543301
}]
Multi-value fields
Any field type can contain multiple values if that it allowed for that instance of the field type.
field_hero_media for example contains multiple references to different types of Media entity.
// Reading
"field_hero_media ": [{
"target_id": 1886265,
"target_type": "media",
"target_uuid": "30b318fe-4e3f-44b7-98e8-4822317df658",
"url": "/media/1886265",
"pwamp": {
"type": "gallery",
"data": {
"title": "James Lawton: Aragones won over lovers of the game with sweet blend of style and discipline",
"gallery": [{
"type": "image",
"data": {
"title": "35772.bin",
"description": "Thousands lined the streets of Madrid yesterday to acclaim Spain's Euro 2008-winning squad after a brilliantly executed campaign",
"caption": null,
"copyright": "AP",
"credit": null,
"alt": null,
"doNotReuse": false,
"url": "https://static.independent.co.uk/s3fs-public/thumbnails/image/2008/07/01/02/35772.bin",
"id": "2136516",
"bundle": "remote_image",
"mid": 1886262,
"changed": "1602543301",
"created": "1602543301",
"uid": 0,
"workflow": {
"name": "Published",
"id": "62",
"uuid": "312eeebb-ed05-4519-99a5-3a48c2856a46"
}
}
},
{
"type": "image",
"data": {
"title": "35771.bin",
"description": null,
"caption": null,
"copyright": "EPA",
"credit": null,
"alt": null,
"doNotReuse": false,
"url": "https://static.independent.co.uk/s3fs-public/thumbnails/image/2008/07/01/02/35771.bin",
"id": "2136596",
"bundle": "remote_image",
"mid": 1886264,
"changed": "1602543301",
"created": "1602543301",
"uid": 0,
"workflow": {
"name": "Published",
"id": "62",
"uuid": "312eeebb-ed05-4519-99a5-3a48c2856a46"
}
}
}
],
"bundle": "gallery",
"mid": 1886265,
"changed": "1602543301",
"workflow": {
"name": "Published",
"id": "62",
"uuid": "312eeebb-ed05-4519-99a5-3a48c2856a46",
"firstLetter": "p"
}
}
}
}, {
"target_id": 1886262,
"target_type": "media",
"target_uuid": "1c024fb9-2a7e-4e4c-ad97-651c5b2c2488",
"url": "/media/1886262",
"pwamp": {
"type": "image",
"data": {
"title": "35772.bin",
"description": "Thousands lined the streets of Madrid yesterday to acclaim Spain's Euro 2008-winning squad after a brilliantly executed campaign",
"caption": null,
"copyright": "AP",
"credit": null,
"alt": null,
"doNotReuse": false,
"url": "https://static.independent.co.uk/s3fs-public/thumbnails/image/2008/07/01/02/35772.bin",
"id": "2136516",
"bundle": "remote_image",
"mid": 1886262,
"changed": "1631845801",
"created": "1602543301",
"uid": 0,
"workflow": {
"name": "Published",
"id": "62",
"uuid": "312eeebb-ed05-4519-99a5-3a48c2856a46",
"firstLetter": "p"
},
"extra": {
"imageSize": {
"width": 650,
"height": 433
}
}
}
}
}]
// Writing
"field_hero_media ": [{
"target_id": 1886265,
"target_type": "media"
}, {
"target_id": 1886262,
"target_type": "media"
}]
Fields that are read only or that are set by the API
There are many fields who's values are set when the entity is updated by the API and so no interaction with these fields is expected or accepted by the API.
pwamp, path, uuid & url are a few examples of these, below is a list of top level properties of the node type article which should never be set by any API Client.
There will be more on other entity types.
"nid": [],
"uuid": [],
"vid": [],
"type": [],
"revision_timestamp": [],
"revision_uid": [],
"revision_log": [],
"created": [],
"changed": [],
"promote": [],
"sticky": [],
"revision_translation_affected": [],
"path": [],