August 10, 2020

Exposing GeoJSON and more through a GraphQL API

Sebastian Scholl

8base’s last major update to it’s GraphQL API was the use of "Loose Typings" in GraphQL to Allow Dynamic Grouping and Aggregation Queries. Since then, the engineering team has been hard at work building another powerful capability that has been requested by both the 8base developer community and required by our own services organization. That is GeoFields with location based filtering and distance calculations!

Let’s check out a few examples to demonstrate what’s now possible!

Location Based Filtering and Queries

With GeoFields, developers are able to filter records based on geo-coordinates. This opens up a ton of possibilities for map and location based applications! Think apartment listing services, dating apps, delivery apps, and more!

In the example below, we’re using a simple filter to query a list of Apartment Listings that are less than 10 miles away from the specified latitude and longitude coordinates.

Location based query using a distance filter on 8base GraphQL API
Response for location based query on 8base GraphQL API

While a simple distance calculation using a Point is cool, the API goes much deeper. Per the GeoJSON spec, support is built in for distance calculations from Points, Multi Points, Line Strings, Multi Line Strings, Polygons, Multi Polygons, Geometry Collections, Features, and Feature Collections.

For unit types, miles, meters, and kilometers are supported with all predicates supported on distance calculations (less than 10 miles, more than 12 kilometers, exactly 101 meters, etc).

Worth noting as well is that bounds calculations have also been implemented and are ready for use on any GeoField. This means that records can also be queried when a geographic bounds input is passed as the filter using any one of the following predicates.

Predicates available on the 8base GraphQL API for GeoFields

All of the types detailed above can be further investigated in a GraphQL client using a Documentation Explorer! 

Distance Calculations in Query Responses

While it’s important to be able to filter records based on locations and geographic bounds, sometimes it’s the calculated result that’s needed - regardless of whether a filter is used. With the introduction of extraFields to the API, developers are now able to specify calculated results that get returned in the API response.

For example, maybe you need to know how far each restaurant in a list is from a user’s current location. With extraFields, this could easily be accomplished like so!

Query list of restaurants with extraField generated on 8base GraphQL API
Response for restaurant query on 8base GraphQL API

Additionally, keep in mind that an extraField can also get used in the filter if necessary!

Using extraFields as filter arguments in 8base GraphQL API

While extraFields were added to support the GeoField use case, it will be expanded in the future to accommodate more advanced API capabilities!

Atomic-operations with updateByFilter

Another great improvement to the API was the introduction of the updateByFilter operation. This was originally a simple task intended to help developers apply the same update to more than one record at a time. However, as our development team thought more about it they took a different direction that - very likely - will influence the future design of 8base’s GraphQL API.

With the updateByFilter operation, all field types accept atomic-operation inputs as to update their values. This means that text, number, date, and switch type fields can all be manipulated in a single API call using type specific atomic-operations.

For example, let’s say that you need to update all the names and startDates for future Events in your database due to the pandemic. Accomplishing this in a single API call is as straightforward as the following.

Updating events using updateByFilter with atomic-operations on 8base GraphQL API

Response when using updateByFilter on 8base GraphQL API for atomic-operations

To experiment more with this, hop into an 8base workspace and look up the updateByFilter mutation for any table! Each field type has its own unique set of operations to choose from.

Delete, Restore, and Destroy Records

Lastly, a small but meaningful update that has also been pushed to the API is the release of delete, restore and destroy operations. 

To date, 8base managed soft-deletes so that if a developer accidentally deleted necessary records they could be recovered by our team. That said, it led to edge case validation issues with unique and mandatory fields which were experienced by a number of developers in our community.

With the introduction of the new restore and destroy operations, we’re taking the training wheels off and putting all the power in the hands of the developer. This allows a developer to do the following.

Delete a record via the 8base GraphQL API

Restore a deleted record via the 8base GraphQL API

Permanently destroy a record via the 8base GraphQL API

Wrap up

We hope that you’re excited to hop in and start building something on 8base using these new capabilities! We’d love to hear from you about whether they’re helpful in your current projects, so please let us know what you think.

Ready to try 8base?

We're excited about helping you achieve amazing results.