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 using the web form 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

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 APIs.

    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!

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

  1. Enter a Description.

    Note: Subscribers of the API will see the Description.

  2. Enter Contact information (Name, Email, and URL).

    Note: Use a group instead of an individual if possible.

  3. Leave Terms and License blank.
  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.

    Note: If applicable, enter Additional media types.

  9. Check the applicable box in the Produces section.

    Note: If applicable, enter Additional media types.

  10. Accept the default Lifecycle settings.
  11. Security Definitions default to the Client ID security. You can add additional security options by clicking Add Security Definition add icon.

    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.
    3. Select Application from the Flow drop-down menu.
    4. Click Add Scope.
    5. Enter a Scope Name in all lowercase, no spaces.

      Note: It is recommended to use your API name in the scope name field.

    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.
    12. Enter the same Scope Name you entered previously (all lowercase, no spaces).
    13. Enter the same Scope Desription 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.

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

  12. Enter a Description for each security definition.
  13. Click Add Security in the Security section.
  14. Check all available boxes:
    • oauth-1 (OAuth) (If appplicable)

      Note: Any Scopes will also display. Leave them checked.

    • Basic (If applicable)
    • api-key-1 (API Key)
  15. Click Add Property add icon in the Properties section.
  16. Click the new property.
  17. Enter endPointUrl in the Property name field.
  18. Click Add Value and enter the applicable Sandbox, Test and Production URLs.
  19. Click Add Path add icon in the Paths section.

    Paths section with add parameters information

  20. Enter the Path.

    Note: Include the paramater in curly brackets. (i.e., /path/{parameter})

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

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

  35. Click Test.

    Test icon

  36. Verify Sandbox is selected under Catalog.
  37. Enter a Name to create a new product.
  38. Click Save save icon.

    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

  39. Click Create and Publish.
  40. Click Next.
  41. Select an Operation.
  42. Click Authorize.
  43. Enter an assignmentId in the Parameters section.
  44. Click Invoke.
Last Updated: 
Friday, April 21, 2017