Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create API documentation #124

Closed
20 of 21 tasks
QaysarA opened this issue Jul 21, 2020 · 11 comments
Closed
20 of 21 tasks

Create API documentation #124

QaysarA opened this issue Jul 21, 2020 · 11 comments

Comments

@QaysarA
Copy link

QaysarA commented Jul 21, 2020

As a internal VA developer
I want to access API documentation for VANotify
to enable integration with VANotify

In scope:
Documentation for endpoints currently in postman collection including:

Organization:

  • create
  • update
  • get

User:

  • create
  • update
  • get

Service:

  • create
  • update
  • get

Template:

  • create
  • update
  • get one template
  • get all templates

API Key:

  • create API Key
  • revoke API Key
  • get one API Key
  • get keys

Other:

  • send notification

  • get notification status

  • how JWT is generated
    - we need to make sure there is a way for consumers to interact with the API without knowing the secret

  • Sync with team to consider if all endpoints listed above should be shared externally to other VA devs. "Process" chat seems to be needed. -> Discuss this during desk check.

Notes:

  • format is Open API
  • No automatic updates to documentation
  • We have Json Schema definitions for some of the endpoints. Consider using tooling that can convert Json Schema to Open Api

Out of Scope:

  • Publishing documentation somewhere where it can be accessed via Open API UI
@sarahproof
Copy link

Do we know how we want this documentation to be accessed? Would it be deployed with the app?

lingtran added a commit that referenced this issue Jul 28, 2020
Co-authored-by: Phil Herbert <pherbert@thoughtworks.com>
Co-authored-by: Marisa Hoenig <marisa.hoenig@thoughtworks.com>
lingtran added a commit that referenced this issue Jul 30, 2020
… documentation

Co-authored-by: Saman Moshafi <saman.moshafi@thoughtworks.com>
saman-moshafi-va added a commit that referenced this issue Jul 31, 2020
Co-authored-by: Marisa Hoenig <Marisa.Hoenig@thoughtworks.com>
marisahoenig added a commit that referenced this issue Jul 31, 2020
Co-authored-by: Saman Moshafi <saman.moshafi@thoughtworks.com>
marisahoenig added a commit that referenced this issue Jul 31, 2020
Co-authored-by: Saman Moshafi <saman.moshafi@thoughtworks.com>
@jsmithVA
Copy link

jsmithVA commented Sep 2, 2020

Reviewed the users endpoints. Found the following issues:

  • for POST create and POST update user, state is listed as a boolean in the response but it is actually a string

  • No error conditions are documented for POST create (ex. malformed request) or POST update (ex. user not found)

  • The documentation says that e-mail address is only required when auth is set to email_auth, but it is required when it is set to sms_auth as well. Mobile number is only required when set to sms_auth.

  • There is no documentation for a GET single user endpoint though it appears to work. It will also need error condition documentation.

  • POST update user lists both email and mobile number as not nullable, but mobile number is nullable as long as auth is set to email_auth.

@jsmithVA
Copy link

jsmithVA commented Sep 9, 2020

Reviewed the services endpoints. Found the following issues:

  • Need error code documentation (example: duplicate service name on POST create and POST update)

  • GET all services and POST create service list whitelist as an array with an object of arrays. But it returns as just an array

  • GET single service endpoint exists but is not documented

  • POST update service shows inbound_url as a url format but the API requires a uuid

@philherbert philherbert self-assigned this Sep 14, 2020
philherbert added a commit that referenced this issue Sep 14, 2020
* makes "active" property not required when creating organisation
* adds documentation of errors when creating organisation
* returns full organisation details when getting single organisation
* adds documentation of 404 when getting single organisation
philherbert added a commit that referenced this issue Sep 14, 2020
* "Organisation" to "OrganisationSummary"
* "OrganisationResponse" to "OrganisationDetails"
philherbert added a commit that referenced this issue Sep 14, 2020
philherbert added a commit that referenced this issue Sep 14, 2020
philherbert added a commit that referenced this issue Sep 14, 2020
philherbert added a commit that referenced this issue Sep 14, 2020
philherbert added a commit that referenced this issue Sep 14, 2020
…allows for variable keys in an object

the API returns keys that are service IDs, but this spec will currently match any string keys. openapi spec 3.1 will include "patternProperties", which will allow us to specify the format of keys
see OAI/OpenAPI-Specification#687
philherbert added a commit that referenced this issue Sep 14, 2020
* inbound_api and whitelist are both lists of ids
@jsmithVA
Copy link

jsmithVA commented Sep 16, 2020

Reviewed template endpoints:

  • Subject is required when type is email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants