Skip to content

Latest commit

 

History

History
137 lines (97 loc) · 4.21 KB

README.md

File metadata and controls

137 lines (97 loc) · 4.21 KB
Raw

Scouting America API

This attempts to document the APIs of Scouting America.

Table of Contents

Introduction

Scouting America has APIs used by their applications. Those APIs are documented here in the hopes that volunteers can find creative uses to better serve Scouting.

This project documents the APIs using the OpenAPI specification.

  • OpenAPI specification
  • OpenAPI specification testing, using Optic
  • Postman collection

Installation

You will need NodeJS to validate the API. Otherwise, your favorite editor or OpenAPI tool will do. Install the dependencies.

npm install

Setup

Some API calls require authentication or parameters, such as a user's ID to get a person's Leadership History /advancements/youth/${userId}/leadershipPositionHistory. These are configured as shell variables in the config file, config.sh.

Variable Description
userId User ID of the person. Not the same as Member ID.
TOKEN JWT token for authentication to protected endpoints. docs/authentication.md

Some tests will fail if you do not change the default values in the config file.

Usage

View the API documentation

Point your favorite OpenAPI tool at the openapi.yaml file in the API's directory.

Validate the API

The tests are run using Optic. The test checks the API response against the specification.

npm run openapi-test

Update the OpenAPI Specification

  1. Write the test case in the test file api.scouting.org-command.sh.
  2. Run the test command npm run openapi-test.
  3. Validate the response for the test case.
  4. Run the update command npm run openapi-update.
  5. Optional: Manually modify the updates.
  6. Run npm run openapi-test to see the updates.

Example

Edit the file api.scouting.org-command.sh.

# Get a list of countries
"$CMD" "$OPTS" "$OPTIC_PROXY"/lookups/address/countries
# run the test command and validate the response
npm run openapi-test

> test
> optic capture api.scouting.org/openapi.yaml

{"ranks": [{"id": "1","name": "Scout"
...
"632"},{"name": "Zambia","short": "ZM","id": "633"},{"name": "Zimbabwe","short": "ZW","id": "634"}]
✔ Finished running requests
✔ GET /advancements/ranks
  ✓ 200 response, ✓ 400 response

100.0% coverage of your documented operations. 1 requests did not match a documented path (3 total requests).
New endpoints are only added in interactive mode. Run 'optic capture api.scouting.org/openapi.yaml --update interactive' to add new endpoints
# run the update command, validate, and select "yes" if you want to document the response
npm run openapi-update
...
✔ Finished running requests
✔ GET /advancements/ranks
  ✓ 200 response, ✓ 400 response

Learning path patterns for unmatched requests...
> /lookups/address/countries
✔ Is this the right pattern for GET /lookups/address/countries › yes
Documenting new operations:
✔ GET /lookups/address/countries
# run test again to see the updates
npm run openapi-test
...
✔ Finished running requests
✔ GET /advancements/ranks
  ✓ 200 response, ✓ 400 response
✔ GET /lookups/address/countries
  ✓ 200 response

100.0% coverage of your documented operations. All requests matched a documented path (3 total requests)

Postman Collection

You can use Postman to easily make API calls. Download Postman and you can find the collection here

A backup of the collection is stored in the postman directory.

Contributing

Just open a pull request if you'd like to contribute.

License

Apache License version 2.0