SSW Foursquare

Rules to Better API Management - 3 Rules

Enhance your API management strategies with essential rules that focus on utilizing the right tools, creating effective mockups, and branding your API portal. These guidelines will help streamline your API processes and improve overall user experience.

  1. Do you know the best tools to manage APIs?

    When building APIs one of the challenges is in how to document the API for other developers to consume.

    Using a tool that automates this is extremely valuable as it helps avoid the biggest bugbear of developers, stale documentation. This resulted in a number of standards being developed for specifying APIs. Swagger and OpenAPI being being the most common, but there are a few others.

    Azure API Management

    The best tool for use in medium to large organizations is Azure API Management (APIm for short). It has all the features other API Management tools and wraps everything up in a very nice UI.

    By supporting Code First APIs, APIm can generate the Swagger documentation from your API code. For the developers consuming your API this is really fantastic!

    APIm allows you to centralize all your APIs and provide a consistent front-end interface for developers. You also get to securely provide all your APIs behind a single static IP address.

    You can use APIm to secure your APIs, improve API discoverablility, transform existing services and even mock services for testing.

    Pros:

    • Very nice UI compared to many alternatives
    • Import API definitions from Swagger, OpenAPI, WSDL, etc
    • Centralized API management

    • API policy management (aka request processing pipeline)

      • mutate incoming and outgoing requests
      • XML to JSON and vice verca
      • Add/Remove/Modify request headers
      • Redirects
    • Caching
    • Rate limiting
    • API Versioning
    • Response Mocking
    • Security features

    • Developer Portal

      • API Documentation
      • Branded APIs

    • Product customization

      • expose parts of any API as individual products
    • Monetization (sell your API)
    • Custom Identity Provider
    • Free Developer Tier
    • Comprehensive SLAs

    Cons:

    • Pricing is complex - Standard to Premium scales exponentially
    • Lots of advanced features, requires a lot of learning

    Watch Adam Cogan and William Liebenberg explain more about Azure API Management.

    Figure: Good Example (more comprehensive)

    For smaller organizations one of the http://swagger.io products may suit better. They are free to start with until you start looking for more advanced features. The feature set even on the paid tiers is still significantly more limited than Azure API Management, however the cost is also much lower.

    Figure: Good Example (for small teams or projects)

  2. Do you know when to mockup your API?

    Designing your API up front can be very useful where you have a significant amount of backend development to complete before there is sufficient functionality for front end development to easily commence.

    Rather than waiting for the backend to be complete, the APIs can be agreed on up front. Tools like Azure API Management then allow you to mock up the APIs with sample data, allowing the front end development to commence much sooner.

    The key benefit of using mocked APIs is being able to present the frontend to stakeholders for feedback really early.

    First, watch the first 5 minutes of this video for a general introduction:

    Watch Adam Cogan and William Liebenberg discuss the benefits:

    Steps to create and test a mocked API endpoint

    To complete the following steps, you need to create an instance of Azure API Management in your subscription.

    TIP: If you have Azure Credits, the Developer (NO SLA) edition is the cheapest option to test most of the features offered by API Management.

    Step 1 - Create Blank API

    1. Select Blank API

    step1 create blank api
    Figure: Create a blank API

    Step 2 - Describe your API

    step2 describe your api
    Figure: Describe your API

    1. Click Create

    Step 3 - Add an Operation

    1. Select your API from the API list
    2. Click Add operation
    3. Specify the Display name, Name and URL of your operation
    4. Display name is a UI friendly display name that shows up in the Operations list
    5. Name is the programatic name of the operation that can be referenced programatically in policies

    step3 add operation
    Figure: Adding a new Operation

    Step 4 - Add response

    1. Click Add response
    2. Select the appropriate response code (e.g 200 OK)

    step4 add response
    Figure: Add a response

    Step 5 - Add representation

    1. Specify the Content Type as application/json
    2. Specify the Sample as { "data": "fake" }
    3. Click Save

    step5 add represtntation
    Figure: Add a representation for your response with fake data

    step5 operation done
    Figure: Operation added successfully

    Step 6 - Add Mock Response Policy

    1. Click Add policy
    2. Select Mock responses

    step6 add mock response policy
    Figure: Add the Mock Response policy

    Step 7 - Choose response

    1. Choose the response representation to return as a Mock (e.g. 200 OK, application/json)
    2. Click Save

    step7 choose response representation
    Figure: Choose the response representation

    Step 8 - Test your Mocked API

    1. Make sure your API is selected
    2. Click the Test tab
    3. Click the FakeData operation
    4. Note the "Mocking is enabled" notice
    5. Click Send

    step8 test mock api
    Figure: Testing the mocked api operation

    Step 9 - Inspect Mocked API response

    1. Notice the 200 OK status code
    2. Notice the fake data response in the message body

    step9 inspect mocked api reponse
    Figure: Response from the mocked operation

    Step 10 - Call your API using a REST Client

    1. Add a new GET request to your REST Client
    2. Specify the API Uri such as https://william-ssw.azure-api.net/data

    3. Add the subscription header Ocp-Apim-Subscription-Key and value

      • you can copy the value directly from the operation HTTP Request section
      • or, from the API Management service | Subscriptions blade
    4. SEND your request
    5. Verify the 200 OK response and the mocked data

    step10 call from rest client
    Figure: Calling our Data API from a REST Client

    Conclusion

    Mocking API responses is awesome! You are able to quickly add mocked responses for all your API endpoints without even having a real backend implementation, and your front-end application can make REAL API calls.

  3. Do you know how to brand your API portal?

    Azure API Management provides a Developer Portal where the automated API documentation can be provided using your own corporate branding.

    If you are looking to sell access to your APIs, this is a fantastic feature because you can combine your corporate identity into the user interface that your customers will be seeing.

    The Developer Portal is open-source and available on GitHub and you can even host it yourself.

    Microsoft already provides a very nice tutorial for how to customize your API Management Developer Portal.

    Watch Adam Cogan and William Liebenberg discuss the benefits.

We open source.Loving SSW Rules? Star us on GitHub. Star
Stand by... we're migrating this site to TinaCMS