Everything in the BOP Digital Platform’s database can be accessed and manipulated via the platform’s REST API, which is a method of allowing different programs to "talk" to each other. Through the API, we make platform data accessible in several different formats. The format most useful to non-technical users is probably as a .tsv (“tab separated values”) file that can be imported into a spreadsheet application like Google Sheets or Excel. By following the directions later in this section, you can write a simple query in the URL bar of your browser that will allow you to target, sort, and download the data you’re looking for based on criteria you specify (like “contains,” “less than,” “greater than,” etc.).

For more technical users, we transform data from how it is stored in the database into a format called JSON (JavaScript Object Notation). This makes the platform’s data accessible in a standard, widely used/understood format that most developers are familiar with. JSON is also fairly readable to non-developers- here’s an example of how JSON is used to represent one entry from the Sites table in the platform’s database, the site Bush Terminal Park:

[

    {

        "_id": "5aa8337061d6e00b838b30a3",

        "bodyOfWater": "Upper Harbor",

        "boroughCounty": "Brooklyn",

        "latitude": 40.654318,

        "longitude": -74.019763,

        "name": "Outer Lagoon, Bush Terminal Park",

        "nycParkId": "BT15",

        "nycParkName": "Bush Terminal Park",

        "propertyOwner": "NYC Department of Parks and Recreation",

        "state": "NY"

    }

]

Additionally, we make geospatial data accessible using a specific type of JSON called GeoJSON, which contains the information necessary to plot platform data on a map as points, lines ("line strings"), and shapes (“polygons”). Using GeoJSON, we can import platform data into popular mapping applications like ArcGIS, Google Maps, and mapbox.

(Without an API, in order to access data from the database, a developer would need to write queries using either the specific language for that database [or a client library for that database written in a backend language]- and there are dozens of different databases and languages for accessing them. By providing an API, we make it much easier to access this data.)

We also use the platform’s API in the frontend of the platform itself. This allows the frontend developer to access and manipulate data from the database independently of how the code is written on the backend- an example of "decoupling."

With the Digital Platform's API, a unique URL (and there can be thousands or even millions of these URLs for just one website) is created to represent each object OR collection of objects. (You can think of an object as one item/record/entry in a database, and a collection of objects as a whole table in a database.) These unique urls are called "endpoints." One example of an endpoint for the BOP Digital Platform would be the database ID for one site in the “Sites” table in the database: <https://platform-beta.bop.nyc/api/sites/5aa8337061d6e00b838b30a3>. Another example would be the collection of sites (essentially, the entire “Sites” table in the database): <https://platform-beta.bop.nyc/api/sites>. This endpoint allows you to access the full list of sites in the database, along with all of the properties, or fields, for each site, such as latitude and longitude, body of water, NYC Parks name, borough, state, and more.

NOTE: to download the full table from the database as a .tsv file via the API so you can work with it as a spreadsheet, append (add to the end) the following to the url: /export.tsv

Example: https://platform-beta.bop.nyc/api/sites/export.tsv

The routes page <https://platform-beta.bop.nyc/api/routes> lists all of the paths to the endpoints that can be accessed via the API, a description of each endpoint, the methods for accessing them, and the parameters each endpoint accepts. (We’ll explain parameters in the next section.)

The documentation page <https://platform-beta.bop.nyc/documentation> also lists the API endpoints.

Collections can be filtered in various ways to return the specific data you’re looking for. We use different "parameters" to do this filtering. In the context of this API, a “URL parameter” is used to access ONE object from the database, using its database ID (a unique number given to each object in the database). For example, this is the url used to access one object in the database via the API- the site Bush Terminal Park: https://platform-beta.bop.nyc/api/sites/5aa8337061d6e00b838b30a3

The other type of parameter we use is a "query string parameter," which is used to modify a request for either one object or a whole collection. Query string parameters filter, sort, and limit the objects being returned.

All query string parameters are added to the end of the API endpoint URL. For example, here’s a somewhat complicated endpoint with multiple query string parameters in it: https://platform-beta.bop.nyc/api/sites?q=boroughCounty/Brooklyn/name/contains:pier&limit=25&offset=50&sort=bodyOfWater,-longitude

It’s what you’d type if you wanted to return the list of sites where each site meets the following criteria:

• The site has "Brooklyn" in the “boroughCounty” field in the database

• The site’s "name" field contains the word “pier”

...and then limit that list to only 25 sites per page, "offsetting" (not displaying) the first 50 results and starting with the 51st result, from a list that has been sorted by:

• First: body of water (alphabetically ascending)

• Second: longitude (in descending order, signified by the "-" sign)

Here are the types of query string parameters we’re using:

To filter a collection of objects, you need to identify what criteria the results must meet, and this has to be written in a specific format, or "syntax," in order to work. In this API, these criteria are expressed as “field/value” pairs. For example, in the “Sites” table in the database, each site has fields like “name” and “latitude.” “name” would be a field in a field/value pair, and “Outer Lagoon, Bush Terminal Park” would be the value. To find all sites that meet the criteria of having the exact “name” of “Outer Lagoon, Bush Terminal Park,” you would type the following into your browser:

https://platform-beta.bop.nyc/api/sites/?q=name/Outer Lagoon, Bush Terminal Park

You can type the full name into the browser including the commas and spaces. Your browser automatically converts certain characters like spaces into a format that servers understand. (This is called percent-encoding, but you don’t need to worry about understanding it to use the API.) In the example above, your browser will turn what you typed into the following url:

https://platform-beta.bop.nyc/api/sites/?q=name/Outer%20Lagoon,%20Bush%20Terminal%20Park

And will then display this JSON:

[

    {

        "_id": "5aa8337061d6e00b838b30a3",

        "bodyOfWater": "Upper Harbor",

        "boroughCounty": "Brooklyn",

        "latitude": 40.654318,

        "longitude": -74.019763,

        "name": "Outer Lagoon, Bush Terminal Park",

        "nycParkId": "BT15",

        "nycParkName": "Bush Terminal Park",

        "propertyOwner": "NYC Department of Parks and Recreation",

        "state": "NY"

    }

]

Looking at this same example, you can see that the URL is broken up into several parts separated by "/":

• The first part is the regular URL for the platform: https://platform-beta.bop.nyc

• The second part is how you access the API: /api

• The third part is the specific table/collection in the database: /sites

• The fourth part is the query string parameter, containing first the field: /?q=name

• ...and second, the value: /Outer Lagoon, Bush Terminal Park

Here’s the basic syntax (note that the words [in brackets] are placeholders for what you’d type in- you don’t actually type in the brackets themselves):

https://platform-beta.bop.nyc/api/[table in the database]/?[parameter type]=[field]/[operator type]:[value]

These criteria are expressed as "field/value" pairs, optionally specifying a comparison operator the values should be checked with.

For example, for objects that have a "name" and "count" field, you could retrieve objects from this collection in the following ways:

• Retrieve all objects whose name is exactly "Test Object":

  name/Test Object, or name/is:Test Object

• Retrieve all objects where count is greater than 25:

  count/gt:25

• Retrieve all objects whose name contains "Test" (case sensitive), and with a count less than or equal to 10:

  name/contains:Test/count/lte:10