Communicating stability and support of an API

[Ryandaydev]

This is an issue for discussion on this topic. Please post your feedback as comments below

For a consumer to begin using an API, it is important that they know how much they can rely on it.

The following are my own definitions of two important qualities that allow an API consumer to rely on it:

Stability - The API will continue to operate in its current state for a reasonable period of time.

Support - Questions or issues submitted by an API Consumer will be responded to and resolved. (https://github.com/GSA/api-standards#avoid-an-api-ghost-town-responding-to-issues-and-questions)

• Assumption 1: Different APIs will be on different points of these two spectrums throughout their lifecycle from development to full support to deprecation.

• Assumption 2: the most critical point is to communicate accurately and realistically where an API falls on those spectrums. In the absence of clear information, the API Consumer will be forced to make assumptions, which may be overly optimistic or pessimistic.

Discussion (the discussion is about communicating, not addressing the stability or support itself):

• Question 1: What is the best way for a GSA API Owner to accurately communicate the current stability of an API?
• Question 2a: What is the best way for a GSA API Owner to accurately communicate the current support of an API?
• Question 2b: What measures can GSA put in place to identify APIs that are not being supported any longer and may need to be decommissioned or marked historical? (https://github.com/GSA/api-standards#decommission-unsupported-apis)

[Ryandaydev]

Q1: Communicating stability

Some options might be:

• A published roadmap with time frames for new features versions, etc.
• A general statement like "no changes planned for the near future" or "major changes coming in the next 6 months" or "planning to decommission this in the next year"
• Clear versioning (part of the standards already)

[Ryandaydev]

Q2a: communicating support

Options include:

• Some type of agreed stage or title like "alpha, beta, live"
• a statement about how quickly you'll respond like "we try to answer emails within 2 days" or "github issues will get a reply in 48 hours"
• Formal service level agreement (SLA)
• A more informal "customer pledge" such as "Our pledge to you is that we will acknowledge your email or post within 48 hours and give a realistic idea of when we can provide you the information requested. If we can't fix the issue or make the change, we will let you know that, too".

[pammiller0]

Ryan I was going to say what you have already said: A roadmap if there will be new features added, clear versioning and how long each version will be supported. If there will be no planned development we should say that as well. On communicating I think that a formal SLA would be appropriate for a bigger project with more resources (to maintain the SLA). Make sure team members are dedicated to supporting the API - or at least responding to the issue/inquiry.

[pammiller0]

Another thought about supporting an API. I think it is important to communicate how to test the API and use its test data. Does the end user need a test account? Is there test data and where? - Is this in scope for this conversation?

[Ryandaydev]

@pammiller0 Testing and test data is another good topic to discuss and funnel to the standards. Here's an issue I created on that topic: https://github.com/GSA/api-standards/issues/42

[gbinal]

Here's some more thoughts I'd add:

Question 1: What is the best way for a GSA API Owner to accurately communicate the current stability of an API?

I don't have too many ideas here other than by clearly communicating a rate limit on the API documentation. That serves to reassure developers of a certain threshold of usage they could reach with the API.

Question 2a: What is the best way for a GSA API Owner to accurately communicate the current support of an API?

Prominently link to a public feedback forum, preferably a GitHub issue tracker, and be responsive to comments and questions that appear there. This communicates to potential users of the API that they can expect support when using the API.

Question 2b: What measures can GSA put in place to identify APIs that are not being supported any longer and may need to be decommissioned or marked historical? (https://github.com/GSA/api-standards#decommission-unsupported-apis)

• Each live API should have at least one point of contact in the GSA API working group.
• There should be a twice-annual status check that the GSA API working group runs where each API program is asked to reaffirm the status of their API, properly decommission their API if it's no longer active or supported, and report any new APIs from their programs or that they have heard of from other programs.

[neelmadhavsphadke]

The API Documentation page seems to be the best place to provide any details about the APIs including versions, support & availability. May be the documentation template should include a place holder for Stability & Support sections. Also, accessing the APIs via api.data.gov ensures proper access control.

[jillmakr]

Most of the pertinent things have already been said, and everything is agreeable.

1. I agree that any API details should be included in the documentation. A full roadmap doesn't seem necessary, but any expected changes and a general timeline / description of those changes should be included. An update that changes are coming should be made at least a month prior so that developers can prepare.

The frequency of changes made to an API should also be communicated. This may be partially implied by the status of alpha, beta, and such, but users will want to know the stability.

2. Expected response time, such as 48 hours is good to include as well, assuming it can be met.

2b) I'm not sure bi-annual tests are necessary unless the site/API is no longer being actively developed. If someone at GSA did want to take the responsibility of being the API manager of sorts, they could maintain subscriber status and set up a notification for themselves to check things if they haven't gotten any updates in 6 months to a year's time. Of course, the assumption here is that the APIs are functional if active development is occurring (one would hope this is the case), but it saves that person from having to check every site every six months.

[mvogelgesang]

@Ryandaydev I agree, the use of alpha and beta tags would be valuable. Talking to various teams here, the definitions can be a bit loose so it may be beneficial for the team to either say "here is what we mean when we say beta" or we make the suggestion to follow a commonly agreed-to standard.

In regards to Q2b, an easy sign that an API is not being maintained is when the open api examples stop working. I'm sure there is some way that we can test for it but that'd be a clear sign that an end point changed, the service is no longer available, and/or the documentation cannot be trusted to match reality.