Version Management in ReAPI

Overview

• Simplicity in Versioning: ReAPI offers an easy way to manage multiple versions of a service, providing a straightforward approach to API versioning. This feature allows you to maintain different iterations of your APIs efficiently.

• Initial Version State: When you create a new version in ReAPI, it starts with empty content, allowing you to define the version according to your needs and preferences.

• Manual Updates: It’s important to manually update the content of a new version once you’re satisfied with the changes in the live version. This ensures that the version accurately reflects the desired state of your API.

• Incorporating Further Changes: If additional modifications are needed after the initial update, you must re-update the version to include these changes. This ensures that all improvements or adjustments are accurately captured.

This process helps maintain consistency and accuracy across different API versions, enabling controlled updates without disrupting existing integrations.

Live Version vs. Named Version

Live Version:

• Real-time Updates: The “live” version in ReAPI automatically updates with every edit and save you make, making it ideal for ongoing development and testing. It always reflects the latest changes.

• Reader View: When accessing an API, the reader view uses the live version by default, ensuring viewers see the most current state of the API.

Named Version:

• Stable Releases: Named versions function as official releases. Once created, a named version captures your API’s state at that point and becomes an independent version. This is helpful for marking stable milestones or completed features.

• Consistency and Reliability: Named versions are generally not changed after creation, which keeps them stable and reliable, especially important for production environments.

• Public Sharing: Only named versions can be shared publicly. This ensures that external users or partners access a stable, tested version of your API, reducing the risk of exposing unfinished or unstable features.

• Dependency Management: If your API relies on components from other services, creating a named version resolves these dependencies by incorporating them into the version. This makes the named version self-contained and independent of external services, enhancing its stability and portability.

This distinction between live and named versions helps you effectively manage the development lifecycle, supporting both iterative development and stable release management while ensuring dependencies are properly handled.

Making Changes to a Release

There are times when you need to make changes to a released version, such as fixing a typo or addressing a minor issue. To update a named version, follow these steps:

1. Create a Temporary Service:

   • Open the version edit dialog and create a temporary service. This copies the content into a new temporary service where you can make changes.

2. Make and Save Changes:

   • Edit the temporary service as needed and save your changes. Make sure all necessary updates are applied.

3. Publish Back to Named Version:

   • Once you are satisfied with the changes, publish the content back to the named version. Only the latest named version can be updated with the corrected content.

4. Delete the Temporary Service:

   • Finally, delete the temporary service from the dialog. This is important because the temporary service will use your service quota like any normal service.

Note: When editing a release, remember that it is self-contained and should not add dependencies on other services. If you need to create a version that relies on other services, you should clone the service instead of editing the release directly.

These steps ensure that you can efficiently make necessary corrections to a release without disrupting your workflow or exceeding your service quota.