Announcing FaunaDB API v3

Author: Summer Schrader
Date: August 18, 2020

---

We are happy to announce the availability of FaunaDB API v3. This release adds four new functions and deprecates one function. In this release, we also introduced a substantial change to our API versioning strategy--a change that will allow us to ship new features faster without introducing breaking changes.

To learn more about any of the changes discussed here, please read our official documentation on API versioning, ContainsPath(), ContainsField(), ContainsValue(), and Reverse().

New API versioning strategy

As of today, you might notice that the v3 drivers send an api_version field in the header of every query. This allows the server to interpret queries from multiple driver versions, and run their semantics accordingly, without causing breaking changes to apps running on older drivers.

The possibility of introducing breaking changes has slowed us down in the past. We're excited about this new versioning strategy, because it will speed up our release cadence and allow for more substantial improvements to the API.

This new versioning strategy also improves the way in which we communicate and share "beta" functionality with our users. In the past, we tried using a "preview" badge to denote unstable features, but included those features in our (otherwise) production-ready drivers. Moving forward, we will make "beta" functionality more inescapably obvious by only releasing it as part of a "snapshot" version of the driver.

Updates to the Contains function family

API v3 introduces three new functions to the Contains function family: ContainsValue(), ContainsField(), and ContainsPath(). However, ContainsPath() does not actually introduce new functionality and works exactly like the now deprecated Contains() function. We decided to rename Contains() to ContainsPath() to help avoid user confusion.

With respect to our new API versioning strategy, this means that the server will continue to run requests with the Contains() function for all supported driver versions. Future driver versions will remove Contains() in favor of ContainsPath(), but your app will remain unaffected until we remove support for the last driver that included Contains(). The Contains() function will only become truly unavailable once the last API version that supports it becomes unsupported by the service.

ContainsPath()

Exactly like Contains(), ContainsPath() checks to see if a path exists in an object. This is useful when you need to distinguish between objects, arrays, or documents that contain a nested path and those that do not. For example, the following query returns true because the path ['inventory', 'apples'] exists in the provided object.

ContainsPath(
  ['inventory', 'apples'],
  {
    store_id: 623,
    inventory: { apples: 0 },
    employees: 7
  }
)

ContainsField()

The new ContainsField() function behaves a little like the above ContainsPath(), but only takes one field for the path. For example, the following query returns true because the field 'inventory' exists in the provided object:

ContainsField(
  'inventory',
  {
    store_id: 623,
    inventory: { apples: 0 },
    employees: 7
  }
)

ContainsValue()

Finally, the most exciting addition to this function family is ContainsValue(). This new function checks for the existence of a particular value in an array, set, or object. For example, the following query returns true because the value 7 exists in the provided object:

ContainsValue(
  7,
  {
    store_id: 623,
    inventory: { apples: 0 },
    employees: 7
  },
)

Please note that ContainsValue() only checks the top-level of objects, so the below would return false:

ContainsValue(
  0,
  {
    store_id: 623,
    inventory: { apples: 0 },
    employees: 7
  },
)

In this case, you would use a Select() to target what you need. See the documentation for more examples.

New Reverse() function

The new Reverse() function was inspired by community requests and this open source FQL library from Eigil Sagafos of ShiftX. Reverse() simply takes an array, page, or set, and returns the reversed version. Here is a simple example, using the data model above:

Reverse([
    {store_id: 623},
    {inventory: { apples: 0 }},
    {employees: 7}
])

[
    {employees: 7},
    {inventory: { apples: 0 }},
    {store_id: 623}
]

See the documentation for more complex examples.

Conclusion

While API v3 introduces only a few new functions, we feel that our new API versioning strategy heralds broader changes in how we work here at Fauna, and how we interact with our community.

For a taste of what's to come in future releases, our engineers are hard at work getting our streaming feature ready for beta testing, improving our GraphQL schema import experience, providing better support for third-party authentication providers, and lots of other exciting new features and improvements.

We also take user feedback very seriously in prioritizing our product roadmap, and are always eager to hear from you about how we can improve. Please post comments/suggestions in the "Feedback" category on our forums.