API: Create and Test an API

Overview

This document outlines the procedure for creating and testing an API.

Before You Begin

  1. Submit a request to join the API Directory to publish an API by clicking Request to join a provider organization on the Getting Started page.
  2. Once your request is approved, you will receive 2 emails. In the second email, the long URL will take you to the activation page of API manager.
  3. Log in with your level 1 UMICH credentials and 2-factor authentication (DUO).
  4. Click Confirm to confirm your identity.

Guided Simulation

Simulation: Create and Test an API

Before You Begin

  1. See the Glossary for an alphabetical list of definitions of terms related to APIs and the API Directory.
  2. See the API Directory Field Description page for context around the fields and sections in the API Directory while creating an API.

Step-by-Step Procedure

The same information from the simulation above is explained in a step-by-step format.

  1. Click Navigate to...

    menu icon

  2. Click Drafts.
  3. Click the APIs tab.

    Note: You will see all of the APIs developed by your provider organization members.

  4. Click Add.
  5. Select New API.
  6. Enter a Title for the API.

    Note: The Name field will default based on the value in Title field.

  7. Click Create API.
  8. Click Got it!

    Note: This is a one time message and you may only see it if this is your first time in the API Directory.

Important: Click Save save icon often to avoid losing work.

  1. Enter a Description. Subscribers of the API will see the Description.
  2. Enter Contact information (Name, Email, and URL). Use a group instead of an individual if possible.
  3. Leave Terms and License blank.

    Note: Each API will be required to provide a meta-data document that describes the API and how to use it. This document will include the Terms of Service.

  4. Enter External Documentation information (Description and URL).

    Note: The external documentation should provide information on how to use the API. Make a copy of the Using the Department API Google Doc, update it, and then copy the link into the URL field.

  5. Accept the default value of https in the Schemes section.
  6. Delete the value in the Host field. Do not enter anything in this field.
  7. Base Path automatically populates. You can change this path, but it cannot be left blank.
  8. Check the applicable box in the Consumes section. If applicable, enter Additional media types.
  9. Check the applicable box in the Produces section. If applicable, enter Additional media types.
  10. Accept the default Lifecycle settings.

    Note: See below if you need to reference the default Lifecycle settings.

    add icon.
  11. Note: Policy Assembly will be skipped over at this time, but users will return to this section later in the process.

  12. Security Definitions default to the Client ID security. You can add additional security options by clicking Add Security Definition add icon.

    Note: The security definition refers to the Published API security.

    Note: Adding an OAuth security definition is recommended. To add an OAuth security definition, complete the following set of sub-steps:

    1. Click Add Security Definition add icon.
    2. Select OAuth from the drop-down menu. Scroll down to complete the following steps.
    3. Select Application from the Flow drop-down menu.
    4. Click Add Scope.add icon.
    5. Enter a Scope Name in all lowercase, no spaces.

      Note:

      • Scope refers to what information the client app can retrieve using the OAuth token that is generated using this scope. The client application requests an OAuth access token using the scope name as a required parameter. The access token thus generated will be able to get the data only for the API for which it is binded/enabled.
      • It is recommended to use your API name in the scope name field.
      • Scope is unique per provider organization. Developers will be able to see all scopes when creating an API.
    6. Enter a Scope Description.
    7. Click Save save icon.
    8. Click All APIs.
    9. Click on the applicable OAuth Token Provider.

      Note: Refer to the API Developer Cheat Sheet for a list of token provider APIs.

    10. Click OAuth 2 on the left navigation or scroll down to the section.
    11. Click Add Scope add icon. Scroll down to complete the following steps.
    12. Enter the same Scope Name you entered previously (all lowercase, no spaces).
    13. Enter the same Scope Description you entered previously.
    14. Click Info on the left navigation or scroll up to the section.
    15. Increase the right-most digit of the Version by 1.
    16. Click Save save icon.
    17. Click All APIs.
    18. Click on your API.
    19. Enter the Token URL in the previously defined OAuth Security Definition.

      Note: Refer to the API Developer Cheat Sheet for a list of Token URLs sorted by provider organization.

  13. Enter a Description for each security definition.
  14. Click Add Securitysave icon in the Security section.
  15. Check all applicable boxes:
    • oauth-1 (OAuth) Any Scopes will also display. Leave them checked.
    • Basic
    • api-key-1 (API Key)
  16. Click Add Property add icon in the Properties section.
  17. Click the new property.
  18. Enter endPointUrl in the Property name field.
  19. Click Add Value and enter the applicable Sandbox, Test and Production URLs.
  20. add icon
  21. Click Add Path add icon in the Paths section.

    Paths section with add path button

  22. Enter the Path. Include the parameter in curly brackets. (i.e. /path/{parameter})
  23. Click Get.
  24. Click Add Parameter.

    Note: Adding a Parameter is not required.

    Paths section with add parameters information

  25. Select Add new Parameter.
  26. Enter the Name of the parameter (without brackets).
  27. Select Path from the Located In drop-down list.
  28. Enter a Description for the parameter.
  29. If applicable, add additional parameters.
  30. If applicable, use the Tags section to make your API more easily searched by tag.
  31. Click Policy Assembly on the left navigation or scroll up to the section.
  32. Click Edit Assembly.
  33. Click Invoke.
  34. Enter the Title and Description.
  35. Overwrite the existing value in the URL field with: $(endPointUrl)$(api.operation.path).
  36. Click Save save icon.

    Note: The API is not published, but is ready to test.

  37. Click Test.

    Test icon

  38. Verify Sandbox is selected under Catalog on the left side of the screen.
  39. Enter a Name to create a new product.
  40. Click Save save icon.

    Note: While it is not required to add an OAuth security API, if you did add an OAuth security API, you must bundle it with your API in order to allow access to your API once published.

    Note: If you added an OAuth security definition to your API, complete the following set of sub-steps:

    1. Click All APIs.
    2. Click Products.
    3. Click your product.
    4. Click APIs on the left navigation or scroll down to the section.
    5. Click Add API add icon.
    6. Check the box for the applicable OAuth Token Provider.
    7. Click Apply.
    8. Click Save save icon.
    9. Click All Products.
    10. Click APIs.
    11. Click your API.
    12. Click Assemble.
    13. Click Test.

      Test icon

    14. Click Create and Publish.
    15. Click Next.
    16. Select an Operation.
    17. Click Authorize.
    18. Enter an assignmentId in the Parameters section.
    19. Click Invoke.
Last Updated: 
Tuesday, June 13, 2017
ITS.umich page: