usepa / cam-api-portal Goto Github PK

Some content in data and apps team channel

Maybe create channel in CAMD suite development Team

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want to easily contact someone for help/questions related to the CAM API portal
So that I can successfully use the CAM APIs

Acceptance Criteria

Given a user clicks on a contact us button
When the page loads
Then they can either fill out a form or contact someone directly

Given a user fills out a form
When that form is submitted
Then this form sends an email to a shared mailbox that potentially creates a ticket

Development Notes

Investigate what options are available and discuss what is necessary for the CAP API Portal

Testing

Test Description

Verify that whatever action a user takes to contact us, we are notified and can respond

Assumptions and Pre-Conditions

Assume the user clicks the button/link

Test Data

Test account/email info to put into a form etc

Steps to be Executed

1. Click the contact us button
2. Fill out form or get contact email
3. Verify we can receive this communication

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

• Figure out what access is needed
• Determine web area
• Demo drupal cms
• Possible password/hidden mode on production?

Sent email to CAMD web master. Waiting on response.

Previous wireframe: https://www.figma.com/proto/pYenfFzGn6iIl4lnA1nXbs/CAM-API-Product-Designs?node-id=276%3A1185&scaling=min-zoom&page-id=276%3A939&starting-point-node-id=276%3A1185

Example from VA: https://developer.va.gov/explore/authorization?api=claims

Outcome:
Basic wireframe in either Adobe XD or another free tool
Start with mobile first design
1 mobile wireframe
1 desktop 1024p

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want to see a list of resources available for the CAM API
So that I can better understand the data, APIs, and how I can use them

Acceptance Criteria

Given a list of resources
When a user visits the resources/help page
Then the list of resources should be displayed as cards with descriptions and links

Given a resource card
When a user clicks on the card
Then the user should be taken to the subpage with that resource or linked to the external resource

Given a set of resource cards
When a user resizes the page
Then the cards should adjust to fit on the page

Development Notes

See wireframe for reference

Testing

Test Description

Verify all the cards link to the appropriate resource. Verify the cards adjust when screen is resized.

Assumptions and Pre-Conditions

n/a

Test Data

A set of test resource pages

Steps to be Executed

1. Load a set of resources as cards
2. Visit the resources/help page
3. Resize screen and check that the cards are displayed appropriately
4. Click the cards and verify they either redirect the user to a subpage, or open an external resource in a new tab

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user visiting the CAM API Portal
I want to see a description of what the CAM API is and the available resources
So that I can find the information I'm interested in and discover more information

Acceptance Criteria

Given a user visits the homepage
When the page loads
Then they should see a subheader with navigation dropdowns, a system updates banner, a button to request an API key, a description of the CAM API and the tools it supports, a what's new box, and a set of cards linking to the docs and help & resources

Development Notes

See the wireframe for reference. This page should be composed of the other react components that have been created and at most the unique content should be the description and configuration of each component (e.g. injecting the content for the cards for API docs subpages and Help & resources subpages).

Testing

Test Description

Verify each component is displayed and loads appropriately. Verify that the page resizes appropriately for mobile and desktop sizes. Verify the components contain the appropriate information and link to the correct places.

Assumptions and Pre-Conditions

n/a

Test Data

n/a

Steps to be Executed

1. Load the page both in mobile and desktop sizes
2. Verify each subcomponent is loaded and displays appropriately
3. Verify each interactable component is interactable and does the appropriate thing (i.e. links go to the correct location, modal pops up for the request API key, dropdown menus work for the subheader, cards go to the appropriate place)

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a developer
I want a high fidelity wireframe with production text (home page) and layout (all pages) to use as reference when creating React components
So that I can create production ready components for use

Acceptance Criteria

Given low fidelity wireframes (mobile and desktop)
When content is finalized
Then we should have high fidelity wireframes (mobile and desktop) for the layout and content in Invision to use as reference

Development Notes

Want the layout and content. The finer details are not as important.
See the low fidelity wireframe in invision. The content in this original wireframe, particularly the card content, has gone through review.

Testing

n/a

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

The create-create-app scripts generate multiple files that we need to place in one html document for the Drupal environment.

• Generate an html template with the necessary tags
• Test pasting in the generated js and css to this template and create a draft in Drupal
• Create etc folder at the top level
• Create drupal-template.html file with scripts and css

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user (developer)
I want to see the swagger page for an API with a description and additional info
So that I can use endpoints in my own work/project

Acceptance Criteria

Given any CAM API
When a user visits an API subpage
Then a description and any potential additional information should display at the top with the embedded swagger page below

Given a generic API subpage component
When a developer is creating the API docs subpage
Then they should be able to dynamically create as many API subpages as there are APIs

Development Notes

See the wireframes for reference. This component should be generic enough to create any number of subpages without significant effort to create new pages.

Testing

Test Description

Verify the page loads appropriately with the swagger component and responds to mobile and desktop sizes

Assumptions and Pre-Conditions

n/a

Test Data

Given any OpenAPI spec and description text, this component should be able to render the page given props.

Steps to be Executed

1. Supply a description/ any additional info and an OpenAPI spec url to the component
2. Test that the component renders the info appropriately and the swagger page is interactable
3. Verify that the page responds to mobile and desktop sizes

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

• Site: http://localhost:9080
  New Alerts
  • Content Security Policy (CSP) Header Not Set [10038] total: 3:
    • http://localhost:9080
    • http://localhost:9080/robots.txt
    • http://localhost:9080/sitemap.xml
  • X-Frame-Options Header Not Set [10020] total: 1:
    • http://localhost:9080
  • Server Leaks Version Information via "Server" HTTP Response Header Field [10036] total: 6:
    • http://localhost:9080
    • http://localhost:9080/robots.txt
    • http://localhost:9080/sitemap.xml
    • http://localhost:9080/static/css/main.a617e044.chunk.css
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • ..
  • Timestamp Disclosure - Unix [10096] total: 11:
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • ..
  • X-Content-Type-Options Header Missing [10021] total: 4:
    • http://localhost:9080
    • http://localhost:9080/static/css/main.a617e044.chunk.css
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
    • http://localhost:9080/static/js/main.75eb7b37.chunk.js
  • Information Disclosure - Suspicious Comments [10027] total: 1:
    • http://localhost:9080/static/js/2.52669c8b.chunk.js
  • Modern Web Application [10109] total: 2:
    • http://localhost:9080
    • http://localhost:9080/static/js/2.52669c8b.chunk.js

View the following link to download the report.
RunnerID:1627682188

As a team member, I want to know the google analytics to know visitor traffic to the cam API portal

Check how this is impacted by a single page web app

Maybe look into Google Tag Manager or whatever else is used for react apps.

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user visiting the API docs
I want to see all the available APIs available with short descriptions
So that I can quickly find what I'm looking for and go straight to the docs

Acceptance Criteria

Given a user visits the API docs subpage
When the page loads
Then there should be a short description or instructions at the top and a set of cards below that hold the titles, descriptions, and links to APIs

Given no changes to the content
When the page is resized
Then the cards should dynamically adjust to the size by moving to the next row or expanding to the row above

Given a user is on their mobile device
When the page is loaded
Then the cards should all be in one column fitting within the width of the screen

Development Notes

See the wireframes for reference

Testing

Test Description

Verify the cards are visible in a mobile and desktop view. Verify the cards can be clicked to visit the appropriate pages. Verify the navigation via the subheader works and users can get back to the homepage or navigate elsewhere

Assumptions and Pre-Conditions

n/a

Test Data

n/a

Steps to be Executed

1. Open the API docs subpage
2. Click on each API endpoint to go to the appropriate subpage
3. Resize the page and verify the cards respond accordingly and move to fit in the screen size

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

• Remove ECMPS endpoints and tags
• Change the whats new box text letting users know that it is a draft site and the final site is in development
• Change the info banner to a whats new box next to the intro text, then move the API key form below the intro text
• Change the API signup to the inline js form like the FACT API
• Include links to swagger pages from endpoint cards

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want resources for the CAM API
So that I can better understand and utilize the APIs

Acceptance Criteria

Given a resource (e.g. FAQ, API Guide, Release Notes, etc)
When a user visits the page
Then A title, description, and information are displayed

Given a resource page
When a user visits the page
Then a unique URL for that page should be displayed in the address bar and should be linkable

Development Notes

See wireframe for reference. The component should accept any React components as the body. The component should have props for the title, description and body content.

Testing

Test Description

Verify the component can be used with any resource type and content.

Assumptions and Pre-Conditions

n/a

Test Data

Generic resource content with varying React components (e.g. accordions, cards, buttons, etc)

Steps to be Executed

1. Provide varying types of content to the React component
2. Verify the content loads appropriately
3. Verify you can generate multiple resource page components and link to them

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

As an advanced user I want to submit a question that's not answered to learn more about the data

Create research spike first

• How does the built-in contact us component work in drupal? Would it be sufficient?

As a DAHS vendor I want to know which endpoints are relevant to ECMPS to quickly find what I need

• Modifications to data resources page
• Modifications to power sector data page
• Possibly link to CAM API portal from re-engineering FAQ

As a developer I want to see an example of data that may be returned from each endpoint

• Build bundle
• Unit tests
• Security scans (CodeQL)

Research what the look and feel and navigation may be. Use the existing wireframe and the VA developer page as reference.

• Take into account changes from original high fidelity wireframe and our restrictions in the Drupal environment.
• Will the swagger page be embedded, separate page, etc
• How does swagger respond to mobile sizes
• What replaces the subheader?
• Can we have the system updates bar

VA Example: https://developer.va.gov/explore/authorization?api=claims

Existing wireframe:
https://www.figma.com/proto/pYenfFzGn6iIl4lnA1nXbs/CAM-API-Product-Designs?node-id=276%3A1185&scaling=min-zoom&page-id=276%3A939&starting-point-node-id=276%3A1185

Outcome:

• One page document

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a CAM API user
I want to see all the available options and pages I can visit in a subheader
So that I can quickly navigate to the content I want

Acceptance Criteria

Given that a user has visited the CAM API portal home page
When they are at the top of the page
Then they should see a subheader with options to reach the API documentation, help/support, and register for an API key

Development Notes

Utilize the reusable component created by CVP for the re-engineering

Testing

Test Description

Test that the subheader is visible at the top of the page and is not sticky as you scroll to the bottom. It should only be visible at the top.

Assumptions and Pre-Conditions

Assume to be on the home page of the portal

Test Data

N/A

Steps to be Executed

1. Visit the CAM API Portal home page
2. Inspect the header for all the required links
3. Test that each link takes you to the appropriate page/resource

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

As a general user I want to know which APIs are available to me on the first page to avoid missing anything and to discover more data

• Prettier can be used to format code so it's consistent across the project
• Prettier can be run in a pre-commit hook using Husky and lint-staged
• Information on how to set this up is located here.

Research task

Build/bundle

• Webpack

Testing

• Jest

Security

• Dependabot
• CodeQL
• OWASP

Accesibility

• ?

Outcome:
onepager

As a regular user of these data, I want to see release information to understand what has changed

Can you do this with swagger pages?
Maybe pulling in semantic release info from GitHub?

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a developer and maintainer
I want to ensure that the application is secure and protected against common threats
So that sensitive systems can be protected

Acceptance Criteria

Given a dynamic javascript web app
When content changes on a single page
Then the OWASP ZAP scan should be able to scan the changes

Development Notes

Potentially achievable with Structural Parameters or via plugins like this article mentions: https://blog.xaviermaso.com/2018/10/01/Scanning-modern-web-applications-with-OWASP-ZAP.html

Testing

Test Description

Verify OWASP ZAP scan can scan all the pages within the web app and all the forms

Assumptions and Pre-Conditions

n/a

Test Data

Create some obvious issues OWASP ZAP can pick up and place them in places that are rendered in dynamic content

Steps to be Executed

1. Generate known OWASP issue
2. Place this issue in the web app that are not rendered on the home page
3. Scan the app with OWASP ZAP scan and see if it finds the pages

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a visitor to the docs
I want to easily see the available api endpoints and resources in a mobile friendly way
So that I can quickly navigate to what I want to see

Acceptance Criteria

Given a resource that needs to be displayed
When the page loads
Then a card with a header and simple descriptive text will appear in a grid, that when clicked, takes you to the appropriate page

Given a generic card
When the card is clicked
Then the respective page is loaded

Given a generic card
When links to subpages are added to the description
Then those links should be clickable and redirect to those subpages

Given a generic card
When supplied a React component
Render the component on the card

Development Notes

See the wireframe on invision

Testing

Test Description

Verify that the card contains a header and a body that is reusable and clickable

Assumptions and Pre-Conditions

Assume the page the card describes is exists

Test Data

n/a

Steps to be Executed

1. Load the relevant page
2. Click on the card or any links in the card and verify that it links to the appropriate place
3. Resize the page to verify the card displays appropriately in mobile view

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

As a general user I want clear instructions on how to access the APIs to access the data without obstacles

As an academic researcher I want to access additional information about CAMD data and CAMD programs

Link to data resources page?
Site navigation bar on the left for CAMD web area?
Link to site map?

As a general user I want to sign up for an API key without having to navigate to a separate page to quickly access data

link to GSA website for api key form

Add to Actions pipeline

https://www.adrianbolonio.com/en/accessibility-github-actions/

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want to see an FAQ before I use the "contact us" option
So that I can get my question quickly answered

Acceptance Criteria

Given a generic resource page React component
When FAQ content is provided to the component
Then a new FAQ resource page is rendered

Given an FAQ resource page
When a user visits the resources/help subpage
Then a card with a title and description of the FAQ page should appear

Development Notes

See the wireframe for reference

Testing

Test Description

Verify that the FAQ page is rendered and linkable from the resources/help subpage

Assumptions and Pre-Conditions

n/a

Test Data

n/a

Steps to be Executed

1. Visit the resources/help subpage
2. Verify a card exists for the FAQ page and that it links to the FAQ subpage
3. Verify the page renders appropriately in mobile and desktop

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

Fix the unit test in the skeleton project and test the create-react-app scripts for running unit tests

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want to quickly see important system updates
So that I can plan accordingly

Acceptance Criteria

Given a system update (e.g. offline for maintenance)
When a user visits the homepage
Then they should see a banner displaying the system update

Given no system updates
When a user visits the homepage
Then they should not see the banner

Given a user scrolls down the page
When they go beyond the length that the subheader is visible
Then the banner should also go out of view with the subheader

Development Notes

See the invision wireframes for reference

Testing

Test Description

Verify the banner displays appropriately under the subheader in mobile and desktop view. It should stay with the subheader and not move with the page.

Assumptions and Pre-Conditions

n/a

Test Data

Simulated system update message

Steps to be Executed

1. Simulate system update message
2. View homepage and any pages with the subheader
3. Verify the banner is displayed and sticks with the subheader
4. Verify the banner reacts appropriately to different window sizes
5. Verify that without a system update message, the banner is not visible

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

Contact github admins to enable at the repository level

Split into separate issues based on identified components.

As a DAHS vendor I want to understand the process for obtaining a CDX token to access ECMPS APIs

Create a GitHub action to perform a basic scan

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a user
I want to see release notes for each API
So that I can update my application with any changes

Acceptance Criteria

Given a set of APIs
When a user visits the Release Notes subpage
Then a set of cards for each API should appear that link to the respective release notes

Given a generic react component for a page with cards
When supplied a list of API release notes
Then a page with cards containing titles and descriptions of those release notes should appear and should link to the release notes page

Development Notes

See the wireframe for reference

Testing

Test Description

Verify that all APIs have a release notes card. Verify that the cards render appropriately in mobile and desktop. Verify the cards are clickable and go to the appropriate place

Assumptions and Pre-Conditions

n/a

Test Data

A set of real or test API release notes

Steps to be Executed

1. Supply API release notes data to the generic React component to generate a page with cards
2. Verify the cards have the correct info and are clickable
3. Verify the cards fit in the screen for various sizes

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?

As a user I want to see a short description of all the data available to discover more data

• Investigate what is necessary to deploy to cloud.gov
• Create manifest file for specific droplet settings
• Test deployment to cloud.gov

As an academic researcher I want to see supplemental information for each endpoint to understand what these data represent to decide which is best for my analysis

https://github.com/swagger-api/swagger-ui

There's more information about accessibility in this issue: swagger-api/swagger-ui#7350

Definition of Ready

• Does this meet the INVEST criteria?
• Does this have a clearly defined user?
• Does this have acceptance criteria?
• Does this have sufficient context for the specific functionality being developed (design, business rules, etc.)

User Story

As a developer
I want to be able to fill out a form to sign up for an API key
So that I can request an API Key

Acceptance Criteria

Given a user clicks on any "request API key" button
When the modal displays
Then the GSA form should be displayed asking for the details required for the signup

Development Notes

link to GSA page for API key signup

Testing

Test Description

Verify that the form works is able to submit and won't if fields are not filled

Test Data

A first name, last name, and email to test with

Steps to be Executed

1. Click the "request a key" button
2. A modal is expected to appear on top of the webpage
3. Fill out the form with test info
4. Click the submit button
5. The modal captures necessary information (first name, last name, email)

Definition of Done

• Have all Acceptance Criteria been agreed to and validated by the scrum team?
• Has the code been unit tested and peer reviewed?
• Have the functional tests been executed?
• Have all defects been reviewed and dispositioned, resolved, or deferred?
• Is the user story ready to be deployed to the test/staging environments?