OpenAPI Spec

[Sgtpluck]

🎫 Ticket

Link to the relevant ticket:
Create OpenAPI spec

🛠 Summary of changes

🚨 Feedback requested! (I probably made a lot of mistakes!)

This change is a preliminary spec for the new Attempts API implementation. It follows in the spirit of the Shared Signals Framework (SSF) and utilizes the RISC poll-based SET delivery specification (RFC 8936).

The initial spec includes a configuration, verification, and status endpoint as well as the polling endpoint.

It includes all 65 Attempts API events, which are divided into Registration, Sign In, Identity Proofing, and Account Recovery events. The events were compiled from this schema document, with some small changes for consistency. If any of the data in the events look like it will be difficult or impossible to get, let's talk!

If you'd like to view the documentation in a compiled reference doc, you can:

• check out this branch
• create a redocly.yaml file with the following content:

extends:
  - recommended

apis:
  external@v1:
    root: ./docs/attempts-api/openapi.yml

    theme:
      openapi:
        hideLogo: true

• run in your terminal:

npx @redocly/cli build-docs docs/attempts-api/openapi.yml
open redoc-static.html

(if you click down into the /poll endpoint, you can get to the individual events, as shown in the screenshot. click the carets next to the event names in order to see what data is inside them)

[matthinz]

Is there any linting or compilation (like, a bunch of yaml files ➡️ a single json file) we can do in CI for this?

[zachmargolis]

Is there any linting or compilation (like, a bunch of yaml files ➡️ a single json file) we can do in CI for this?

+1 I am curious if there is an validation we can do on the files, and also eventually what we can do to make sure that our implementation matches what we document

[n1zyy]

I forgot about this gem.

[Sgtpluck]

yeah i am going to see if we can fix this this time around!

[matthinz]

We really, really should try to avoid doing this

[mitchellhenke]

I think we've discussed using the error codes/keys rather than the description

[Sgtpluck]

i just put time on amir's calendar to discuss the technical limitations and what we can do when he's back in the office!

[Sgtpluck]

@matthinz and @zachmargolis yes! there are a bunch of different tools that can do this. i was using redocly as i found recommendations for it generally, and it has a vscode extension. it can both compile into one document and lint.

(to your second point zach, i would like to figure out also how to make sure our implementation matches the spec, but i haven't given much thought to that quite yet.)

[matthinz]

Is there any linting or compilation (like, a bunch of yaml files ➡️ a single json file) we can do in CI for this?

swagger-cli might be a good tool to look into for validation.

It can also compile a bunch of yaml files down to a single JSON file, which would be cool, since we could then ship that JSON file and make it publicly accessible on secure.login.gov

[vrajmohan]

Minor - we should sort all the enum values so that it is easy to look up as well as maintain.

[Sgtpluck]

@matthinz it would also be cool to compile the docs as reference docs in the dev-docs site somehow, to ensure that documentation matches our source of truth! i added a linting step in 9542a03 -- am happy to add a step that compiles to json, but am curious if anyone has thoughts about the best place to insert that in ci?

[Sgtpluck]

Minor - we should sort all the enum values so that it is easy to look up as well as maintain.

@vrajmohan sorted in 033c0e1 !

[mitchellhenke]

Suggested change

	Due to technical limitations, errors for this event will be localized into English, Spanish, or French, depending on the user’s settings, and appear in the “failure_reasons” setting that way.
	Due to technical limitations, errors for this event will be localized into English, Spanish, French, or Chinese (Simplified) depending on the user’s settings, and appear in the “failure_reasons” setting that way.