Apigee has provided a great set of documentation on how their Edge Gateway can be configured. This documentation does not replace it, but instead will help guide the process and outline some standardizations and guidelines.
Guidelines and Standards
- Example: https://api.ucsb.edu/students/lookups
- has a spec name of "lookups-v1" in the "students" folder.
- The name should match the url.
- The folders/groupings of APIs should be based around functional usage.
- students - Student Record Information. Including individual student data, rosters, and aggregated data.
- housing - Housing information for students, faculty, and staff.
- employee - Employee information. Including UCPath and HR information.
- All groupings will have a hidden (but known) "private" folder. These are for APIs that will not be listed publicly but are created to meet one-off needs.
- Versioning should be added with a dash to the end of the spec file name.
- Versioning should be kept to whole number (v1, v2).
- Swagger/Open API imports should be in yaml format.
- Json to yaml conversion can be done at http://editor.swagger.io.
Proof the Spec
Before importing a spec in the API Gateway, first proof the spec at http://editor.swagger.io. Here are some things to look for:
- Ensure the spec points to a valid website.
- Ensure only the https scheme is allowed.
- If there is any Authorization mechanics needs, please ask the API provider to give you test credentials to try it out.
- Test out the spec to see if it returns data. Ensuring the test works isn't a requirement for you, but the developer that sent you the spec should have tested this out themselves.
- The reason testing out the Spec may not work for you is because the API Provider may have locked down the security on their API to only allow calls from particular hosts. Your computer may not be on that list.
Steps to Create
The API service provider should give you an API Spec to import into the system. Before importing the spec, lets look through it at http://editor.swagger.io]. See above in Proof the Spec for more information.
In the Specs section find/create a folder for the functional area that the API will be grouped under. Some example groupings are:
- students - Student Record Information. Including individual student data, rosters, and aggregated data.
- housing - Housing information for students, faculty, and staff including residential services like dining commons.
- employee - Employee information. Including UCPath and HR information.
- The overall folder structure and name of the spec will match the API Proxies url. For now, just create a new Spec.
- And then Copy in the spec from https://editor.swagger.io/ and Save it.
Next up, we'll Create an API Proxy