Standards and Guidelines

  • All APIs are expected to have an corresponding Swagger UI Documentation page created within the Developer Portal (this includes Private APIs).
  • While we hope to one day prevent public access to the documentation of the Private APIs, at the moment we do not have a way of implementing that and Private APIs will also have their documentation accessible to the public. Since the documentation is not the same as access to the data, this is not considered a security risk.

Create an API Documentation Page

  • We would like an API Documentation page created for each API (create link).
    • The API Documentation type needs to have an OpenAPI/Swagger .yaml file in order to generate the page.
      • The easiest way to create the .yaml file is to alter the API Spec that was created during the Apigee Edge setup.
      • The extension of the file must be .yaml, the website won't serve .yml because it's not on a security whitelist.
      • Use https://editor.swagger.io/ to alter the API Spec document.
      • Add a ucsb-api-key to the securityDefinitions and security sections at the top of the file. See the Student Basic Info API yml as an example.
    • Change the host to api.ucsb.edu and the basePath to the correct base path.
    • That should be all the changes that are needed, but please verify the alterations by testing out the API within the editor.
securityDefinitions:
  ucsb-api-key:
    name: ucsb-api-key
    in: header
    type: apiKey
security:
  - ucsb-api-key: []
  • On the API Documentation Page, select the Security desired (Access Approval Required, Auto Approved, None).
  • In general, when creating an API Documentation Page, the Deprecated check box will be left unchecked. (This checkbox is used when updating an API version.)
  • Ensure a URL Alias is defined in the publishing settings. The default value is usually in the format "/content/{page-name}"; the system should suggest a value.

Updating/Deprecating an API Version

  • The expected use case for this is when a new version of an API becomes available. We would like for the documentation linked by the menus of the website to go to the latest versions documentation. But, we would also like for the older documentation to be available through links.
  • Examples:
  • Start by Editing the API Documentation which is going to become deprecated.
    • Change the name of the page to include the version number
    • Check the Deprecated checkbox
    • Ensure the URL Alias is updated to include the version number
  • Now create a new API Documentation page (create link). And follow the steps from Create an API Documentation Page above.
    • Within the body of the new API Documentation add a link to the old version: Previous Versions: [v1.5](/content/student-record-code-lookups-v15)