Apigee Edge Standards and Guidelines

General Conventions

• We should attempt to group the APIs by a functional classification. This will be the root pathing for the url.
• Every grouping will potentially have a /private subpath, which are for APIs that exist with that grouping but are not publicly exposed.
• There is a /misc classification which is for one-offs that we really can't find or create a good classification grouping for. We strive to avoid using it.
• A list of categories that have already been thought about (but could change)
  • /academics
    • /curriculum
  • /administration
  • /dining
  • /housing
    • /residents
  • /students
    • /private (example)
      • /mtdaccess
  • /employees
  • /faculty
  • /misc (This is reserved for APIs that we can't find or create a good classification grouping for. We should attempt to avoid using it.)
• If an API does not fit within a predefined grouping, we should discuss as a group to agree on a new classification grouping.

Specs

• Example: https://api.ucsb.edu/students/lookups
  • has a spec name of "lookups-v1" in the "students" folder.
• The name should match the url.
• Organization named folders should be used to organize the specs.
• Versioning should be added with a dash to the end of the spec file name.
• Swagger/Open API imports shold be in yaml format.
  • Json to yaml conversion can be done at http://editor.swagger.io.

API Proxies

• Example: https://api.ucsb.edu/students/lookups
• Names should match the urls
  • Use dashes to represent forward slashes
• All lowercase
• Do not use dashes in urls. For example, don't use /students-lookups, instead use /students/lookups. This is confusing because the names of API Proxies should have dashes to represent forward slashes (because the API Proxy names don't allow forward slashes).
  • (image goes here)
• Description is required
  • Description should include Contact Information for the Primary Developer
• Versioning
  • Is required in the url
  • The version number can't be in the Proxy Base Path (it will need to be handled by the Spec)
  • Versioning needs to be checked in a shared flow, if it is missing it must be injected after the Proxy Base Path.
  • All calls from Apigee Edge to the Resource Provider will include the version in the url.
  • Example url to Resource Provider: https://registrar.sa.ucsb.edu/webservices/public/lookups/v1

Shared Flows

• Proxy Endpoints PreFlow
  • (Required) ucsb-standard-options-response
  • This shared flow must be the first incoming flow on the Proxy Endpoints PreFlow.
  • This flow will look for HTTP messages using the OPTIONS method. It will return the standard CORS headers needed for browsers to make "test calls" to the api from the developer portal.
  • (Required) ucsb-standard-api-key
  • This will verify that the header 'ucsb-api-key' comes across as a header and is valid.
  • This will verify an API Product is associated with the header. It will check if the API Product is a "readonly" and will set a flag indicating if it is.
  • This will enforce the proxies quota limit for the given client.
  • This will prevent spikes in activity to prevent burst traffic that will cause degradation for other users.
• Proxy Endpoints
  • ucsb-standard-write-access-denied
  • A standardized error message for preventing access to methods that perform updates.
• Proxy Endpoints PostFlow
  • (Required) ucsb-standard-response-headers
  • This shared flow will add the standard CORS headers needed for browsers to make "test calls" to the api from the developer portal.
• Future use cases:
  • Handle a missing version number in the url by automatic injection.