TeleClinic Partner API

The TeleClinic Partner API allows you to embed the services of TeleClinic into your application. Please reach out to us for getting access.

You can find the documentation of each version here:

• v1/: OpenAPI

Versioning policy

Our API is following this versioning schema: MAJOR.MINOR

• MAJOR updates break compatibility. Therefore, when we release a new major version, we keep the previous major version available at a different path in our API. You can access the spec of each major version at the URL listed above.
• MINOR versions are a change of our OpenAPI schema. They usually introduce new functionality while always keeping backwards compatibility. That means that if you generated a client for a previous minor version, that client will still work with the newest version.
  We are not keeping the previous minor version for you available to consume, as the new one will be compatible and be served from the same endpoints as the previous one.
  If you want to make use of new features, you usually need to generate a new client from our spec.

We may also occasionally fix errors without bumping the version. Those updates will not change the OpenAPI spec.

What is a breaking change?

In general, if the API changes in a way that doesn't allow previously released clients to continue working, it's a breaking change.

Examples of incompatible changes, require a new major version:

• Deleting an endpoint
• Deleting a field from a response body
• Renaming a field in a response body
• Adding required request parameters

Examples of compatible changes:

• Adding a new endpoint
• Adding a new field to a response body
• Adding a new optional request parameter
• Removing a value from an enum

(Non-)extensible Enums

Our API is utilizing enums – for example, the treatment state is an enum. The OpenAPI spec does not allow us to differentiate whether the enum is extensible or not. See Issue #1552 of the OpenAPI-Specification.

Depending on the endpoint, we do consider some of our enums to be extensible and others not. As long as the spec doesn't allow us to define it in there, we are using the following table to document what we consider as extensible (and we will add new values in MINOR versions), and what is non-extensible (and requires a MAJOR version)

If an enum is extensible, your client must be able to handle unexpected values! For example, you can prepare your client to assume a default value. We are proposing a way of handling extensible enums in the following table, but you're free to handle those situation as you see fit.

This only applies to enums in responses. Enums in requests are always extensible, since they do not affect old clients (e.g. the "gender" parameter used as a filter).

Enum	Extensible	Suggested Handling
FileType	Yes	Use default "other". Use the mime_type field of the File model to determine what type of document (PDF, ...) is presented to you to offer an appropriate download to the user.
TreatmentState	No	-