Document VA Benefit Taxonomy API for consumers/products

[wesrowe]

Description

User story

AS A Developer of a product that consumes the VA Benefit Taxonomy I WANT the API to be designed and documented in a way that makes it easy to use SO THAT I can efficiently deliver value to Veterans using my product.

Suggested in 3/29/23 meeting by Dave Conlon. Suggestions in that meeting:

• Lighthouse may have docs or a process for good API design
• Cindy Merrill used to do usability research for Lighthouse - see her comment below with resources
• Consider future-proofing steps like providing a unique ID (done)
• Include naming conventions for the API-ID field
• Include life-cycle governance rules around which fields will not change
  • e.g., we will never change a published Official Benefit Name, rather we will sunset the old one and publish a replacement

Engineering notes / background

Drupal Context Drupal provides 2 options for how to serve APIs.

1. GraphQL
2. JSON content API

Within the structure of those options for getting data out of Drupal, we will have downstream customers accessing that API data.

Analytics considerations

Quality / testing notes

Acceptance criteria

• [ ] Documented API fields, accessing via GQL
• [ ] Reviewed by FE engineer for usefulness
• [ ] Saved to product folder for Benefit Taxonomy - either root level of create an api folder

[jilladams]

From backend refinement: we need to work out how we think this is different than GraphQL.

[davidmpickett]

Chatted briefly with @cindymerrill today and she offered to share some resources and bookmarks from when she worked in this space

[cindymerrill]

@davidmpickett Here are some API developer experience resources for you to take a look at:

• https://www.youtube.com/watch?v=o5tI4I_Zz6U
• https://developerrelations.com/developer-experience/ux-of-developer-experience
• https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf

I have more links, but the above look like the most basic and UX focused.

[cindymerrill]

@davidmpickett Is what you'll be doing at all related to the current Facilities API? Here's the documentation for it: https://developer.va.gov/explore/facilities/docs/facilities?version=current

[wesrowe]

Refinement 9/7:

• This is probably part of the effort to build our first FE pages (ie Ben Deets pages) using this API.

Switched epics to the hardening epic.

Architecture topic: down the road, external customers might leverage this data through Lighthouse.

[FranECross]

@davidmpickett Is this ticket moot now based on the recent content modeling/documentation for Benefits Taxonomy? Thanks. cc @dsasser

[davidmpickett]

@davidmpickett Is this ticket moot now based on the recent content modeling/documentation for Benefits Taxonomy? Thanks. cc @dsasser

I think it is moot until we have a likely first consumer of an API (e.g. Chatbot team). It is more theoretical/hypothetical than actionable for the foreseeable future. So I think you can safely close as not planned. Can always reopen at a later date if that makes sense