Lab 3: Publish the Omni Channel API to Exchange


In Lab 1 we examined how to use Anypoint Exchange to facilitate the API discovery process. In Lab 2 we learned how to use Anypoint Design Center to design the specifications for a modern RESTful API. In this lab we will learn how to publish our API to Anypoint Exchange so that API consumers and API developers within the organization are able to leverage the API through "self-service".

One of the biggest challenges encountered by early adopters of SOA was how to scale their development activities. SOA maintains many of the reuse principles that we have discussed in our "API-led" approach to software development. Unfortunately, most SOA efforts could not achieve their reusability objectives because of a few limiting factors including:

  • Poorly documented services

  • Lack of mature tools to facilitate service discovery

  • Over-reliance on limited number of knowledgable resources

  • Burdensome processes for gaining access to services

As a result, many SOA-based initiatives were only able to partially achieve their reusability objectives because developers would adopt the path of least resistance and simply recreate services rather than reuse them. The MuleSoft Anypoint Platform addresses all of these issues by providing innovative tools like Anypoint Exchange that alleviate these challenges.

Let’s take a look at the process for publishing and documenting our reusable Omni Channel Experience API.

Step 1: Complete the Omni Channel Experience API Specification

Before we get started, make sure you are logged into the Anypoint Platform and viewing the Anypoint Design Center screen. You should have your "<username> - Omni Channel Experience API" open and visible. We have only defined a few resources and methods at this point and need to author the full API in order to complete the exercise. Rather than build it from scratch, we have the ability to import an API specification previously constructed for the workshop.

  1. Go to the Setup located at the top right corner.

  2. In the drop down menu select Import from Exchange

    module1 lab3 import from exchange
  3. Look for Omni Channel Experience API.

  4. Select Omni Channel Experience API

  5. Press Import asset

    module1 lab3 choose omni channel exp

    Is going to ask you to replace the root file.

  6. Choose Yes

    module1 lab3 root file
    Anypoint Design Center supports both RAML and Open API specification (OAS) languages when importing an API specification. OAS is a common format popularized by open-source Swagger tools.
  7. Delete the RAML file user-omni-channel-experience-api.raml from your project explorer that we were previously editing. We no longer need that file since the API we just imported replaces that specification. Click the "ellipsis" menu next to your file and then click "delete":

    module1 lab3 ellipsis delete
  8. Delete the omni-channel-experience-api.raml file.

    module1 lab3 ellipsis delete2
  9. Select the new RAML file we imported. You should see the following complete API specification:

    module1 lab3 full api
    Note the extensive use of references to other assets published in Anypoint Exchange. This API designer is using the features of Anypoint Exchange to efficiently reuse common data types, traits, and other API fragments.

This fully formed API specification is ready to be published! Feel free to explore the API using the mocking service if desired.

The full API specification designates that a client_id and client_secret are required to use the API properly. We have not secured our API yet and will cover that in a future module. If you are trying to test the API using the mocking service then you can enter any value for these parameters and it will still work properly._

Step 2: Publish Your API to Anypoint Exchange

  1. Click on the Publish button and then on the Publish to Exchange button.

    Publish to Exchange
    Publish to Exchange
  2. A popup window to capture the attributes that you want to publish to Exchange will appear. Most of these fields will be pre-populated and the RAML will be verified to ensure that there are no errors. Complete the Asset version field with 1.0.0.

    module1 lab3 publish exchange tags
  3. Click the "Publish" button when you have finished reviewing the API name and version information. We have now published our Omni Channel Experience API to Anypoint Exchange for other developers to discover and consume!

    module1 lab3 publish exchange success

    Each time you publish and API Specification you will generate two assets:

    • RAML Spec: This is the RAML Specification. Everybody on the organization can discover the spec and documentation.

    • Rest Connector: This is a connector automatically generated for the API you have just defined. We will cover this in more details on Module 2 and Module 9.

Step 3: Augment the Documentation for Your API

As demonstrated in Step 2, publishing your API to exchange is as easy as a few clicks. However, Exchange has really only just captured the basic attributes and documentation for your API at this point. Ensuring that your API is easy to find and "self-service ready" is your responsibility as an API designer. Let’s find our API in Exchange and add more to our API documentation.

  1. Navigate to Exchange 2.0 from the "hamburger menu" at the top left corner of Design Center.

    module1 lab3 navigate to exchange
    module1 lab3 navigate to exchange2
  2. Use the search bar to find your API if it is not readily visible in the list of Exchange assets. Click on your API once you find it:

    module1 lab3 exchange assets select
  3. Click on either of the "Edit" buttons to launch into edit mode.

    module1 lab3 exchange edit
  4. Exchange assets are documented using "markdown" language. Markdown language is a format-agnostic syntax used for creating documentation independent of how it will be rendered (i.e. HTML, PDF, text, etc). It is used by popular applications like GitHub as the standard way to create software documentation. For more information on markdown please refer to:

    Create your own documentation for your API, or copy the following text into the editor:

    The **Omni Channel Experience API** is used to simplify access to Orders, Products, and the Shopping Cart features required for mobile and e-commerce applications.
    Developers requiring can easily compose innovative applications by leveraging this API to do the following:
     - Retrieve the Product Catalog and details about a product
     - Add products to a stateful shopping cart
     - Search for orders and retrieve their status
     - Create a new order
    module1 lab3 exchange editor markdown
    If you prefer WYSIWYG editing then you can click on the "Visual" button at the top and be presented with a visual editor instead of the markdown-based editor. Both editors product markdown at the end._
  5. Click on the "Save as Draft" button at bottom of screen. Your draft of the API documentation is saved but not published until you formally "Publish" the final updates to Exchange, so feel free to save multiple drafts as you create your documentation.

    module1 lab3 exchange editor draft page
    • You can press Publish, Discard Draft or Exit Draft.

      • Publish - Publish documentation changes to exchange

      • Discard Draft - Throw away changes

      • Exit Draft - Keep changes, but do not publish to Exchange

  6. Press the Publish button. Your documentation changes are now visible on Exchange!

    module1 lab3 exchange editor final page

    Exchange documentation can be comprised of multiple pages. So far we have just created the home page for our API.

    It is common practice to include links to other content like video tutorials in our Exchange documentation. This makes it easier for the interested developer to gain access to all of the documentation required to learn how to use the API.

Step 4: Validate the API

Like in Design Center, in Exchange you can look at the API Summary. The API Summary gives you the opportunity to do a request and call the mock service or an implementation of the API.

We are going to see how can be done.

  1. Go to the API Summary

    module1 lab4 exchange api summary
  2. Press /products/search [GET]

    module1 lab4 exchange product search
  3. On the right side of the panel you will see the GET method to be called.

    You can select from a combo list of available implementation endpoints to call. In this case we only have the mock service and what’s defined in the specification. Later in Module 5, we will add to this list of available endpoints once we complete the API Life Cycle.

    You can see the Parameters and Headers how they are filled.

    In the Parameters tab you can optionally click on the checkbox and see all the optional parameters that can be send.

    module1 lab4 product search
  4. Press SEND and see what happens.

    module1 lab4 exchange product search response

    You can see the mock response and you can see:

    • module1_lab4_http_response: Here you can see the http response and the response time

    • module1_lab4_message_icons: These let you download the response, copy the response to clipboard and format in a better way.

    • module1_lab4_details: Finally there is a detail Tab that will show you the Request Detail. URL, Response and Request headers.

      module1 lab4 response details

Congratulations! You have completed Lab 3.

Congratulations! You have completed all of the labs in Module 1!

Please proceed to Module 2