Index Versions

Overview

Index Versions allow you to utilize our data models to manage your internal provider directory or to maintain an updated state of the default data we provide.

An Index Version is a unique, stand-alone copy of the base data we provide. Two of its important characteristics are:

1. it is only visible to you, and
2. a change made to one index version only affects it, not your other indices or indices of other developers.

Use cases

Provider directory management

If you are using Railway's data models to manage your internal provider directory, you will use an index version that's visible only to you. You can also use multiple indices to maintain multiple provider directories. This comes in handy when you want a different directory per referring practitioner on your clinical team.

Maintain updated data

Railway provides data models and appointment booking capabilities; and so the information we return on practitioners, like accepted insurances or phone numbers, is on best effort. We recommend using external data vendors to retrieve this information.

Instead, we allow you to update our base data such that future API requests from your account return your unique, updated data. For example, let's say you find a practitioner now accepts a new HMO plan but it is not reflected in our base data. You can update the accepted insurance information on your index version so that future API requests will reflect that the practitioner accepts the HMO plan.

How it works

Each index version has a unique id that is prefixed with idx_. The standard index version with our base data is identified through the id idx_standard.

Creating a new Index Version

You can use the POST /index_version endpoint to create and name a new Index Version. By default, the new version will copy over the base data from the standard index (idx_standard), and the ids will remain the same.

Sending API requests

Whenever applicable, the API endpoint accepts the Closure-Index-Version request header. To query a specific index version, you will provide this header along with the corresponding index version (ex: idx_standard).

Therefore, a GET request will return data from the requested index, and a POST request will create, update, or delete data from the requested index. We do not allow changes to the default index (idx_standard), so any attempt to do so will result in a 403 - Forbidden error. You can only make changes to the index versions you have created. Note: you can use the index idx_test_mode_custom to test write endpoints in test mode.

How ids work

Each Railway API resource is identified by a unique identifier — the id attribute. For resources derived from the standard index, the id will be the same across indices. For new resources created on a custom index version, a new id will be randomly generated every time. Therefore, when you are querying the lowest-level resource, always make sure to pass the intended Closure-Index-Version header.

For example, let's say you query the GET /schedules/{schedule_id} endpoint. The Schedule object returns the attribute practitioner which is the practitioner's id. If you want their preferred name, you will need to call the GET /practitioners/{practitioner_id} endpoint to "expand" the id. While making the extra API call, ensure you've passed the right Closure-Index-Version header so you get the data from the intended index version.

Understanding Closure-Index-Version header documentation

The API reference for each endpoint specifies whether or not it requires an index version in the Headers subsection. Each endpoint also has an Introduction guide explaining how to use index versions for its resource (example).