Data Sharing Policy

APIs for creating and manipulating policies

Data Sharing Policies are a main component of the BitBroker system. You will find more details about policies, within the key concepts section of this documentation.

In our sample calls, we use the standard server name and port format outlined for local installations and demos. If you have an alternative API host base URL, then enter it in the box below to update all the sample calls on this page :

Your API Host Base URL

All API calls in BitBroker require authorization. The sample calls below contain a placeholder string where you should insert your coordinator API authorization token. If you already have a token, enter it in the box below to update all the sample calls on this page:

Your Coordinator API Authorization Token

Creating a New Policy

New policies can be created by issuing an HTTP/POST to the /policy/:pid end-point.

In order to create a policy, you must select a unique policy ID (pid) for it.

curl http://bbk-coordinator:8001/v1/policy/over-a-billion \
     --request POST \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "The Most Populated Countries", \
         "description": "Countries with a population of over a billion", \
         "policy": { \
             "access_control": { \
                 "enabled": true, \
                 "quota": { \
                     "max_number": 86400, \
                     "interval_type": "day" \
                 }, \
                 "rate": 250 \
             }, \
             "data_segment": { \
                 "segment_query": { \
                     "type": "country", \
                     "entity.population": { "$gt": 1000000000 } \
                 }, \
                 "field_masks": [] \
             }, \
             "legal_context": [ { \
                     "type": "attribution", \
                     "text": "Data is supplied by Wikipedia", \
                     "link": "https://en.wikipedia.org/" \
                 } \
             ] \
         } \
     }
EOF

This will result in a response as follows:

HTTP/1.1 201 Created
Location: http://bbk-coordinator:8001/v1/policy/country

The following validation rules will be applied to the body of a new policy request.

Attribute	Necessity	Validation Rules
`pid`	required	String between 3 and 32 characters long Consisting of lowercase letters, numbers and dashes only Starting with a lowercase letter Conforming to the regex expression `^[a-z][a-z0-9-]+$`
`name`	required	String between 1 and 64 characters long
`description`	required	String between 1 and 2048 characters long
`access_control`	required	An object describing how data can be accessed
`access_control.enabled`	required	A boolean string either `true` or `false`
`access_control.quota`	optional	An object describing allowable data quotas
`access_control.quota.max_number`	optional	An integer greater than 0
`access_control.quota.interval_type`	optional	One of an enumeration of either `day` or `month`
`access_control.rate`	optional	An integer greater than 0
`data_segment`	required	An object outlining the shared data subset
`data_segment.segment_query`	required	A valid catalog query, from the Consumer API
`data_segment.field_masks`	optional	An array of strings An empty array
`legal_context`	optional	An array of 0 to 100 of object outlining the legal basis of data sharing
`legal_context.type`	required	One of an enumeration `attribution`, `contact` `license`, `note`, `source` or `terms`
`legal_context.text`	required	String between 1 and 256 characters long
`legal_context.link`	required	String between 1 and 1024 characters long Must conform to URI format

Details about the meaning of these attributes can be found within the key concepts section of this documentation.

Policy IDs are required to be unique across an operating BitBroker instance.

You should choose your policy IDs (pid) with care, as these cannot be changed once created.

Data sharing policies are complex objects. You should refer to the detailed explanation of these of the key concepts area, if you are unclear about any aspects of their construction.

Updating a Policy

Existing policies can have their profile updated by issuing an HTTP/PUT to the /policy/:pid end-point.

In order to update a policy, you must know its policy ID (pid).

curl http://bbk-coordinator:8001/v1/policy/over-a-billion \
     --request PUT \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "This is a new name", \
         "description": "This is a new description", \
         "policy": { \
             "access_control": { \
                 "enabled": true, \
                 "quota": { \
                     "max_number": 86400, \
                     "interval_type": "day" \
                 }, \
                 "rate": 250 \
             }, \
             "data_segment": { \
                 "segment_query": { \
                     "type": "country", \
                     "entity.population": { "$gt": 1000000000 } \
                 }, \
                 "field_masks": [] \
             }, \
             "legal_context": [ { \
                     "type": "attribution", \
                     "text": "Data is supplied by Wikipedia", \
                     "link": "https://en.wikipedia.org/" \
                 } \
             ] \
         } \
     }
EOF

This will result in a response as follows:

HTTP/1.1 204 No Content

Great care should be taken when updating policies, since authorization tokens may have been issued in the previous context. The ability to change the definition of live policies is a powerful feature, but comes with responsibility.

The new policy definition will come into play right away (after a small propagation delay). Authorization tokens issued prior to the change, will automatically become subject to the new definition.

The validation rules for updated policy information, are the same as that for creating new policies.

List of Existing Policies

You can obtain a list of all the existing policies by issuing an HTTP/GET to the /policy end-point.

curl http://bbk-coordinator:8001/v1/policy \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON array as follows:

[
    {
        "id": "over-a-billion",
        "url": "http://bbk-coordinator:8001/v1/policy/over-a-billion",
        "name": "This is a new name",
        "description": "This is a new description"
    }
    // ... other policies here
]

Each policy on the system will be returned within this array. Note: There is currently no paging on this API.

Details of an Existing Policy

You can obtain the details of an existing policy by issuing an HTTP/GET to the /policy/:pid end-point.

In order to obtain details of a policy, you must know its policy ID (pid).

curl http://bbk-coordinator:8001/v1/policy/over-a-billion \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON object as follows:

{
    "id": "over-a-billion",
    "url": "http://bbk-coordinator:8001/v1/policy/over-a-billion",
    "name": "This is a new name",
    "description": "This is a new description",
    "policy": {
        "data_segment": {
            "field_masks": [],
            "segment_query": {
                "type": "country",
                "entity.population": {
                    "$gt": 1000000000
                }
            }
        },
        "legal_context": [
            {
                "link": "https://en.wikipedia.org/",
                "text": "Data is supplied by Wikipedia",
                "type": "attribution"
            }
        ],
        "access_control": {
            "rate": 250,
            "quota": {
                "max_number": 86400,
                "interval_type": "day"
            },
            "enabled": true
        }
    }
}

Deleting a Policy

Existing policies can be deleted from the system by issuing an HTTP/DELETE to the /policy/:pid end-point.

In order to delete a policy, you must know its policy ID (pid).

curl http://bbk-coordinator:8001/v1/policy/over-a-billion \
     --request DELETE \
     --include \
     --header "x-bbk-auth-token: your-token-goes-here"

This will result in a response as follows:

HTTP/1.1 204 No Content

Any authorization tokens which were issued for this policy will no longer return any results for any of the end-points which form the Consumer API.