Best Practices for Consuming the Redox API

One thing that sets the Redox API apart from API’s like HL7 FHIR is our ability to rapidly add new elements and get them live in production quickly. Our first focus is always on developer satisfaction, and our drive to make the data model better is well complemented by following some simple rules.

What you can do

Follow Martin Fowler’s Tolerant Reader pattern.

The short version is this:

My recommendation is to be as tolerant as possible when reading data from a service. If you’re consuming an XML file, then only take the elements you need, ignore anything you don’t.

We don’t send XML but the same principle applies to Redox JSON – best to ignore things you don’t need and not try to parse/serialize everything else into strongly typed objects.

What we will do

Being a tolerant reader will set your application up for successful Redox integration. However, we go one step further in trying to be what Saleem Siddqui calls a Magnanimous Writer.

While we don’t meet all the criteria, we follow some basic rules:

We won’t:

  • Change data types of fields in the JSON (string to Array, number to string, etc.)
  • Remove fields that already exist
  • Add additional required fields
  • Decommission a Data Model or Event Type without transitioning you to a replacement

But do expect us to:

  • Add new fields of any data type (Array, string, etc.) to existing data models
  • Accept any additional fields you may send, but ignore them
  • Add new, separate Data Models event types that don’t interfere with your current integration

We have lots of exciting projects in the works that will make using the Redox API even easier and more enjoyable, but following these basic principles will always be the safest cleanest way to integrate with us.