1. To add an API to the API Manager, you must first navigate to the API Publisher (https://api.byu.edu/publisher).
  2. You will be redirected to the BYU Login screen. Please log in using your CAS credentials.
    1. Note: if you are denied access, you probably have not been granted permission to use the publisher. Please contact the api@byu.edu to request access.
  3. You will be greeted by the Publisher home page, which looks like this:

     
    1. On the left-hand side, you'll see a list of options: Browse, Add, All Statistics, My APIs, Subscriptions, and Statistics.
    2. "Browse" enables you to browse through all of the currently-existing APIs, view, and edit them. (Note: The home page defaults to "Browse.")
    3. "Add" enables you to add a new API to the API Manager.
    4. "All Statistics" enables you to view statistics for all APIs.
    5. "My APIs" enables you to view only your own APIs.
    6. "Subscriptions" allows you to view a list of users who have subscribed applications to your APIs. You will also be able to see subscription activity.
    7. "Statistics" allows you to view statistics regarding your own APIs.
  4. To add an API to the API Manager, click the Add button on the left hand side of the page:
  5. You will be presented with three options. Please select the one that best fits your needs:
    1. "I have an Existing API" - Use if you have existing RESTful API endpoints. If you have one, you can give the API Manager a swagger document at this point, and it will pre-populate a large amount of information for you.
    2. "I have a SOAP Endpoint" - Use if you have existing SOAP endpoints. If you have one, you can provide the API Manager with a WSDL URL.
    3. "Design a new API" - Use if you are looking to prototype and mock a non-existent API Endpoint. This option will not allow you to connect to a real backend.

    * Note * - For this example, we will be selecting the "I have an existing API" option and not giving a swagger document
  6. Select your option and then click "Start Creating"
  7. The first step in creating your API is the "Design" stage. Here you will enter in all of the descriptive information about your API and its routes. First, we will fill out the "General Details" section (see image below). The section includes the following information:
    1. Name (Required) - The human-readable name for your API. This will be displayed on the store.
    2. Context (Required) - The URL context path that will be used for access to your API. (i.e., /domains/{domain_name} for a Domain API, or /byuapi/{top-level-resource} for the University API)
    3. Version (Required) - The current version of your API. You will be able to update versions in the future. We typically like to stick with the V1, V2 style of API versioning.
    4. Visibility (Required) - "Public" means that your API will be visible to anyone who has access to the store. "Restrict by roles" allows you to restrict visibility to a list of comma-separated LDAP/GRO groups.
    5. Thumbnail Image (Optional) - This thumbnail will be displayed in the store.
    6. Description (Highly Recommended) - While not required, we highly recommend (and request) that you put in a short description about your API, describing what it is used for and what it provides.
    7. Tags (Highly Recommended) - Tags help organize your API into the "groups" that you see in the API store. It also makes searching easier.
    • Note: There are several fields that have little question-mark symbols on the right-hand side. By clicking these, you will be given further details regarding the proper use of the field/option.
  8. The next step is to fill out the "API Definition" section (located underneath the "General Details" section). This can be done in several ways:
    1. By importing an existing Swagger document. This can be done by clicking the "Import" button.
    2. By editing the definition in an API Manager swagger editor. This can be done by clicking the "Edit Source" button.
      • Please note that this option is only recommended if you are comfortable creating and editing raw Swagger documents
    3. By using the API Manager UI to define your routes. This can be done in the UI on the bottom half of the page.
      • This is the option we will be using in this example to define our API.
  9. To define your routes in the WS02 UI, first delete the existing wildcard routes.
    1. These routes are designed to let every request through. This is not what we typically want for our behavior, because it prevents the API Manager from being able to stop invalid traffic and does not produce very usable documentation. Instead of letting every request through, we want to create a white-list of approved requests.
    2. To delete the existing wildcard routes, simply click on the trashcan icons, located on the right-hand side (see image below).
  10. For each route/endpoint in your API please do the following:
    1. Enter the route into the "URL Pattern" field.
    2. Select which methods are allowed on the route (Get, Post, Put, Delete, Head, or Options [To view "Options", you have to select "more"]).
    3. Click the "Add" button to add the route.
    4. You should now have one new route for each method that you selected. These routes will show up below.
  11. Now, we need to edit the details for each of the routes that you entered. For each route or method entry please do the following:
    1. Click on the path name to expand the details of the route (see image below).
    2. (Optional, but highly recommended) Click on the "+ Summary" link to add a short summary about the endpoint.
    3. (Optional but highly recommended) Click on "+ Add Implementation Notes" to add a longer description about what the endpoint does.
    4. Click the "Empty" link next to "Produces:" and enter the MIME type that the service produces (more information about the MIME types can be found here: http://swagger.io/specification/#mimeTypes).
    5. Click the "Empty" link next to "Consumes:" and enter the MIME type that the service consumes (,ore information about the MIME types can be found here: http://swagger.io/specification/#mimeTypes).

    6. If your endpoint does not take any parameters, then you are now done with this route. However, if your endpoint does have parameters, then for each parameter do the following:
      1. Input the name of the parameter into the "Parameter Name" box and click the "Add Parameter" button (see image below).
      2. Click on the "+ Empty" link in the "Description" field to add a quick summary about the parameter (see image below).
      3. The API Manager tries to make a good guess at the other properties of parameter (Parameter Type, Data Type, and Required). However, if you wish to change any of the other options, you can do so by clicking on them (see image below).
  12. Congratulations! We are finally done with the design step! Now lets move on to the implementation step by clicking the "Next: Implement >" button (see image below).

     
  13. You will be presented with the following screen. Choose "Managed API."
  14. Fill in the section, "Endpoints."
    1. Select an endpoint type. It is recommended that you select "HTTP Endpoint."
    2. (Required): Type in the Production Endpoint.
    3. (Optional): Type in the Sandbox Endpoint
    4. For each Endpoint, click on "Test" (located to the right). The test feature works by checking the root of the endpoint. If nothing exists at the root, it will return "invalid." If the test feature returns "invalid," it will be up to your own discretion whether or not to change the endpoint to something else.
  15. Click on the "Next: Implement >" button at the bottom of the page (see image below).

     
  16. You will be brought to the following screen.

     
  17. Fill out the Configurations Section.
    1. Do NOT check the box "Make this the Default." Checking this box may cause problems down the road for subscribers.
    2. Select a Tier Availability from the drop-down menu. You may select "unlimited," "gold," "silver," or "bronze." This will determine the frequency at which subscribers will be able to call your API.
    3. Select HTTPS ONLY as your transport. If you select HTTP, no one will be able to call your API.
      1. "Transport" refers to the way that the client connects to the API Manager, not how the API Manager connects to the backend.
      2. There are a lot of internal APIs that run on HTTP instead of HTTPS. What you put for your endpoint on the previous page has no bearing on what you select here.
    4. For more information on Message Mediation, click here.
    5. Response Caching should be disabled.If you choose to enable response caching, you may run into problems later on.
  18. Click on "Business Information" to expand the Business Information section.

     
  19. Fill out the Business Information Section.
    1. Type in the name of the Business Owner.
    2. Type in the Business Owner's preferred Email.
    3. Type in the name of the Technical Owner.
    4. Type in the Technical Owner's preferred Email.
  20. For each path, select an authentication type. See the picture below.
    1. "None" = Unauthenticated. If you select "None," any anonymous user will be able to call your API. Do not select "None" unless there is a very compelling reason to do so. By selecting "None," you sacrifice your ability to monitor the API in the API Manager.
    2. "Application" = Client Credentials authentication.
    3. "Application User" = Authorization Code or Implicit authentication.
    4. "Application & Application User" = Client Credentials, Authorization Code, or Implicit authentication. This is the default setting.
  21. (Optional): Select a tier for each individual path. This is helpful if you would like a particular path to be throttled differently than the overall API.

     
  22. Scroll down to the bottom of the page, and click the button "Save & Publish."

     

Congratulations! You have successfully published an API to the API Manager!