Purpose

This issue serves two purposes:

1. to track whether or not the new API can be responsibly stabilized, and
2. to provide a roadmap for getting there.

By responsible stabilization we mean that the stabilization of a new interface should be deferred until no more breaking changes are anticipated for it. Also, before stabilizing an interface we should take the opportunity to review it for ways to make it nicer.

Background

In zonemaster/zonemaster-backend/pull/1054, zonemaster/zonemaster-backend/pull/1083 and zonemaster/zonemaster-backend/pull/1111 a new experimental RPC API was introduced. The new interface is basically a copy of the old one, but with better names and some other improvements.

Status

I believe this proposal is a decent approximation of how we want to go forward. We should discuss it at the next F2F. Until then feel free to share any thoughts in comments below.

I've started populating the list of desired changes in phase 1. I encourage everyone to join me in this effort.

Phase 1: Discovery

We begin by gathering a set of needs and desires for the API to use as a starting point for the rest of the process. We reflect on our current understanding and opinions of the API and what we need from Backend.

Here is a list of activities to help us create and identify issues:

• Identify any new use cases involving the API that we'd like to see implemented, and create issues describing them.
• Identify any existing use cases involving the API where the current API is lacking or problematic in some way, and create issues describing how the situation could be improved.
• Identify any existing plans or wishes for updates to the API in our backlogs.
• Review the API documentation for any improvements and create a issues describing them.

Desired changes

As soon as you create or identify an issue about a desired change, make sure to add it here.

• Formal states for test items zonemaster-backend#960
• Disambiguate usage of the term "test" by using "job" zonemaster-backend#1084
• Insufficient parameter validation in job_status method zonemaster-backend#1105
• When there are no results make job_results return status zonemaster-backend#1117
• Make job_status report proper percentages #1176
• Add custom field to test_results table zonemaster-backend#1116 -- this both about a change of the database and the API
• Updated API methods for batches zonemaster-backend#1119
• Remove client id and version zonemaster-backend#1122
• Avoid abuse of priority parameter zonemaster-backend#1123
• Improved control over queue usage zonemaster-backend#1124
• Emit warnings for deprecated usages zonemaster-backend#1149
• New batch_domains method zonemaster-backend#1151
• Anonymous batch creation zonemaster-backend#1153
• New batch id format zonemaster-backend#1154
• Improved batch status zonemaster-backend#1156
• Simplify authorization model zonemaster-backend#1223
• ...

Phase 2: Refinement

Here we work through all the issues we gathered in the previous phase. We make sure that we have a sufficient understanding of each one and that they fit nicely together.

• Make sure each desired change has a clear design proposal with regard to the API.
• Make sure the design proposals aren't in conflict with each other, and that taken together they would result in a nice API.
• Make sure each desired change is clearly marked up with whether or not it is a (would-be) breaking change.
• Make sure any dependencies between desired changes are clearly marked up.

Phase 3: Triage

Here we make a list that helps us track progress towards an MVP for stabilization.

• For each desired change determined to be a (would-be) breaking change, add it to the list of blocking issues.
• In case we don't think we'll be able to implement all (would-be) breaking changes for the upcoming release we may elect to postpone the stabilization of some of the methods.

Blocking issues

• ...

Phase 4: Implementation

There's nothing to be done in this issue for this phase. All the blocking issues just have to be completed.

Phase 5: Stabilization

Once all blockers are resolved we can go ahead with stabilization.

1. Remove the experimental markings from the new API and mark the old API as deprecated.
2. Close this issue.