Tips to Building a Successful API – Part 3

Featured

If you haven’t read part 1 and part 2 this API series, check the a links on the right 🙂

A successful API is more than a feature; when you view your API as a product, it can be an enabler of your business strategy. Part of the magic of APIs is that creative developers find uses that the API designers never envisioned. If APIs are well designed and easy to use, this can be an enormous benefit and opportunity, turning your service into a platform that can grow in many ways.

A successful implementation encourages developers to use it and share it with others, creating a virtuous cycle where each additional successful implementation leads to more engagement and more contributions from developers who add value to your service. A great API can help you grow an ecosystem of employees, customers, partners who can use and help you continue to evolve your API in ways that are mutually beneficial.

But the promise of APIs can only be realized when target consumers begin to use them. For internal developers, APIs introduce a new way of working and one that will require some buy-in. In addition, internal developers won’t use your API if they don’t believe it’s the best, most efficient way to achieve their goals. ell designed APIs that are easy to use will encourage adoption by internal developers, paving the way to a better-defined, more consistent and maintainable approach to development.

For public APIs, the situation is even more competitive. An ever-increasing pool of APIs is competing for developer’s attention, making the design and ease of use of your API critical to its adoption and ultimately, its success.

Unfortunately, too many API providers build theirs before thinking through the critical success factors, resulting in APIs that fail to meet business objectives. Delivering a great API isn’t hard if you follow a few proven principles. In this post, I’ll demystify some strategies by reviewing the 4 tips of a successful API.

Tip #1: Design for successful APX (API User Experience)

To deliver great APIs, design must be a first-order concern. Much like optimizing for UX (User Experience) has become a primary concern in UI development, optimizing for APX should be a primary concern in API development. An optimal API design enables applications, developers, to easily understand the purpose and functionality of the API so that they can quickly become productive using it. It also allows organizations to focus on getting the design right before investing in back-end implementation, which
is time-consuming and expensive to undo if design issues aren’t identified until after implementation.

The best way to design an API that developers want to use is to iteratively define the structure in an expressive manner and get feedback from developers on its usability and functionality along the way. The API Designer is an example of this concept in action. The API Designer is an open source design environment that leverages RAML, the RESTful API Modeling Language. The API Designer provides an editor for drafting the APIs structure while rendering in real-time an interactive console to enable interaction with the API.

As the API is designed, application developers can interact with it and test its behavior, thanks to an integrated mocking service that returns the values a call to the live API would produce. Because APIs designed in RAML( RESTful API Modeling Language) are concise and easy to understand, application developers can rapidly assess the APIs functionality and usability and offer concrete feedback on ways to improve it.

Tip #2: Optimize for use case scenarios

There is no such thing as a one-size-fits-all API. Even for the same underlying service or set of services, multiple APIs might be required to support different types of users and use cases. An API should be optimized to fulfill a specific business request in a specific context. Too often APIs are modeled after the design of the backend services or applications they expose instead of the use case they fulfill. This results in poor performance of the client application, poor user experience, and ultimately, poor adoption.

To optimize your API for a specific use case, think about how coarse or fine-grained it should be. For example, if you’re designing an API to enable access to sales order status from a mobile device, you need to consider the constraints of that use case. A mobile application has a higher sensitivity to number of network trips, latency and data size than a web application so this API should be designed to limit backend calls and minimize the size of data returned.

In addition, this use case is fairly granular – the API will lookup an order based on the order number and return a status. Therefore, the API should expose this specific fine-grained functionality so it can be invoked independently.

If the underlying service it accesses is coarse-grained and you anticipate building
additional APIs on that service to address additional use cases, consider a tiered approach. Expose fine-grained services that users can access directly, and add coarse-grained services on top of them to support broader use cases. Users can choose to call the fine-grained APIs directly or if they need the combined functionality of multiple fine grained calls they can use the coarse-grained APIs. This API designed in API Designer is an example of an API optimized for this case.

Tip #3: Provide super easy access

Finding an audience for your API begins with publishing it to a portal that allows developers to discover your API so they can begin evaluating it for their use case. The developer portal should include all of the tools developers need to learn about and begin using your API. Developers reviewing your API will only invest a few minutes before deciding whether or not to continue; having information available in a clear and easy-to-consume format will encourage them to stick around rather than go elsewhere. Developers will quickly scan your documentation to get an overview of its functionality then zero in on what it will take for them to get up and running.

From there, they’ll quickly want to see some examples and ideally, start interacting with the API. Developers are far more likely to use an API that includes interactive documentation that allows them to interact with the API over static pages that only allow them to read about it.

The API Portal includes interactive documentation that not only describes the endpoint but also the fields required to call that API and the data that is returned. In addition, you can add code samples to give developers a head start in building the code to access your API in the applications they build. Finally, the Console includes “try it” functionality that allows developers to interact with and test the API. During the design phase before the API has been implemented, a mocking service allows developers to test the API’s behavior and see the resulting body a call to that API would produce. Once the API is implemented, developers can test live.

Tip #4: Build an ecosystem (community)

apiThe application developers who consume your API are not just your customers; they are the ecosystem that will drive your success. Treating them as valued members of your community can drive significant mutual benefit An obvious benefit of a thriving developer community is a wider reach for your API.

To support the organic growth of your API, your developer portal should include an easy way for developers to share knowledge with each other. The Notebook feature of the API Portal demonstrates this concept in action. It allows developers to document new uses they discover for your API to grow the addressable market for your API. In addition, they can share tips and tricks in forums and even add code samples to make it easy for new developers to get started quickly with your API. Finally, a valuable benefit of the community that is sometimes overlooked is that the greater the number of developers using your API, the faster bugs and issues will be identified and communicated so that you can continue to improve the value offering.

In addition, there is a great benefit in having an established communication channel with your developer community. Your API is not a static entity – as new use cases are identified and use of your API expands, enhancements and fixes are inevitable.
When you release a new version of your API, you can easily communicate the enhancements in the new version through your developer portal. You can also quickly assess who’s using each version of your API and communicate an upgrade path to them as you deprecate older versions. Finally, understanding your
developer community and having accurate insight into use cases and patterns provide invaluable knowledge that you can use to enhance your API over time.

Summary

APIs are becoming ubiquitous as their potential to transform business is becoming widely recognized. But delivering a successful API program that achieves defined business objectives requires a systematic approach to designing and managing APIs. Great APIs aren’t difficult to develop if you design for your users and the business
processes the API will support, if you make it easy for developers to find and consume your API, and you actively manage your API developer community as an extension of your business.

Until next time, Rob…

API’s and their business value…

API

In the past few months, I have been focusing a lot of my time around the development of our Nutanix Ready Integrated Program which deals with partner solutions leveraging\cosuming our API (application programming interfaces).  After a lot of research on API programs and consumption patterns, I thought I would share my thoughts and some conclusions on the business side. Not sure if this is considered a blog post or just ramblings, but here we go.

API and DATA

Data is, in many ways, is one of the most valuable assets a business has. A growing number of consumers and businesses are incorporating web and mobile apps into their daily routines, and companies are using data to provide more personalized, tailored experiences to their customers. In addition, companies are analyzing customer and operational behavior to make better decisions. These are some of the valuable new uses for previously isolated data sources.
APIs have emerged as the most accessible way for consumers within the business to extract value out of that data; developers can use them to create new business opportunities; improve existing products, systems, and operations; and develop innovative business models. Analysts can grab new data sources more quickly and pull the data into their analytics platforms. As the keys to unlocking precious enterprise data, APIs need to be combined with enterprise connectivity to actually free the data from systems. The APIs is the piece that makes the data consumable and reusable, thus they become ever more valuable to business.

API Evolution

As more and more APIs come into use, the architecture underpinning them needs to evolve as well – organizations cannot simply attempt to deploy APIs on top of existing monolithic systems and processes and expect an overnight transformation. Rather, the transformation begins with initiatives targeted at new innovative directions for the organization, such as the embrace of microservices, mobile apps, and laying the groundwork for a world of connected sensors. Also, product companies should consider making API framework a key part of their design strategy which would enable end users to adopt their product more rapidly and aggressively.  And above all, embracing APIs will help ensure that these connections are made intelligently and efficiently.  With all of this, I’ve seen there’s a direct connection to business value as well – generating revenue is considered the most important value that APIs provide to the business.
While revenue generation is an important part of the story, the impact of APIs goes much further into organizations, enabling transformation and agility at many levels. APIs enable enterprises to deploy apps quickly, in a repeatable way, which leads to a faster pace of delivery, and the ability to create new and innovative experiences quickly. In addition, APIs can greatly reduce the cost of change, enabling IT and application owners to change apps with minimal impact – especially when there are numerous back-end integrations involved. This is critical to agility since for the most part, the pace of change of the front end applications is much faster than in the back-end applications. APIs also help enterprises achieve operational efficiency, enabling greater visibility and expanded capabilities since every API call from the mobile app to the backend system is tracked and traced through an API key.

What are some examples?

For those who are not familiar with API, some examples are API are like SOAP or  REST. Nutanix uses REST (representational state transfer) based API, and we allow partners and customers to build leverage our API to do some very cool things.  From VM monitoring to solution orchestration, the possibilities are endless.
API
For example, Comtrade, a Nutanix Partner has developed a System Center Operations Manager Management Pack for Nutanix.  It leverages our API to pull metrics into SCOM to correlate with application workloads into a single pane of glass.  In this scenario, an IT Pro can really understand where his bottlenecks are and take action or automate that action.  Now that is the power of API with some DevOPs mixed in!!
To summarize….businesses from every industry are using APIs to add additional value, from increased revenue to increased agility to improved customer experience. Extraordinary changes are taking place in the enterprise which necessitates a new organization and philosophy for utilizing technology.
In a future blog post, I plan to go into the technical aspects of API and use cases.

Until next time, Rob… 🙂

Microsoft Azure Cloud Series – Azure Resource Manager – Part 3

Hello everybody, time to get in-depth with Azure Resource Manager.  But, before I dive into the Azure Resource Manager, I would like to quickly review some of the basics in Azure.  I will start with a rundown of the Azure Global Footprint.  Then, I will go into how Azure charges are incurred.  And finally, I will dive into the Azure Resource Manager V2 and comparing it to the older Azure Service Manager V1.  Sit tight and let’s go for an Azure Ride 😉

Azure Global Footprint
Azure Resource Manager

Microsoft Azure itself is deployed around the world and involves the concept of regions, which is where you select to place and run your code.  Each region has a Microsoft Azure data center.  These data centers are massive facilities that host tens of thousands or, in some cases, hundreds of thousands of servers.  Currently, Microsoft has:

  • Four regions in North America
  • Two regions in Europe
  • Two regions in Asia
  • One region in Japan

As shown above, Microsoft also has a number of Content Delivery Network (CDN) edge points.  They can be used to cache your content and deliver it even faster to end users.
Once you build an application, you can choose any location in the world where you want to run it and you can move your workloads from region to region.  You can also run your application in multiple regions simultaneously or just direct traffic and end users to whichever version of the app is closest to them

How are Azure Charges Incurred?

This may be different for many of you who are familiar with hosting providers and on-premises systems
Simply, with Microsoft Azure, you pay only for what you use:

  • There are no upfront costs
  • There is no need to buy any upfront server licenses; this is included in the price
  • VMs (IaaS and web/worker role) usage is by the minute
  • VMs (IaaS only) that are stopped in Microsoft Azure, only storage charges apply
  • Likewise, if you use a SQL database, through the SQL Database feature in Microsoft Azure, you do not have to buy a SQL Server license—this is also included in the price
  • For compute services, such as VMs and websites you only pay by the hour

This gives you the flexibility to run your applications very cost effectively
You can scale up and scale down your solutions or even turn them on and off as necessary. This also opens up a wide range of possibilities in terms of the new types of apps you can build.

Managing Azure Deployments

Microsoft Azure currently have two management models:

  • Azure Service Manager (ASM) has been around since 2009 and has been due for an upgrade..
  • Azure Resource Manager (ARM), released last summer, supports modern deployment practices. It is designed to be extensible to all current and future services.

Azure Service Manager V1

  • Traditional way to deploy and manage applications hosted in Azure
  • Azure Portal https://manage.windowsazure.com
  • PowerShell / CLI (default mode)
  • REST API

Azure Resource Manager V2

  • Modern way to deploy and manage applications hosted in Azure
  • Azure Portal https://portal.azure.com
  • PowerShell / CLI (ARM mode)
  • REST API
  • Azure Resource Management Library for .NET

Why and what is Azure Resource Manager?

Today’s challenge with Azure Service Manager V1– it’s difficult to…

  • Set and manage permissions – only co-admin and service admin
  • Monitor and have alerting rules – limited to Management Services and basic KPI in portal
  • Billing – through the billing portal
  • Deployment – complex PowerShell to gather all components for an application
  • Visualize a group of resources in a logical view, including monitoring/billing

ASM V1 Portal – Resource Centric Views

Azure Resource Manager
After working with the current ASM V1 for a number of years now, here’s the breakdown:

  • Resources are provisioned in isolation
  • Finding resources is not so easy
  • Deployment is more complex than on-premise
  • Management of app is challenging
  • Proper use of resources becomes more abstract
  • Isolation makes communications a challenge

Ok, Rob, then why does Microsoft still keep ASM V1 in production?  
Answer:  As of the writing of this blog post, not all features have been ported over to Azure Resource Manager V2.  Once all features and services have been ported over, I expect Microsoft to end of life Azure Service Manager V1.

Azure Resource Manager Overview

Azure Resource Manager
Azure Resource Manager enables you to work with the resources in your solution as a group.  You can deploy, update or delete all of the resources for your solution in a single, coordinated operation.  You use a template for deployment and that template can work for different environments such as testing, staging and production.  Resource Manager provides security, auditing, and tagging features to help you manage your resources after deployment.

Benefits of ARM

  • Desired-state deployment
    • ARM does desired-state deployment of resources. It does not do desired-state configuration inside these resources (e.g., VMs), although it can initiate the process of desired-state configuration.
  • Faster deployments
    • ARM can deploy in true parallel as compared to semi-sequential in ASM
  • Role-based access control (RBAC)
    • RBAC is fully integrated with Azure Active Directory
  • Resource-provider model
    • Resource-provider model is intended to be fully extensible.
  • Common interface for Azure and Azure Stack
    • When Azure Stack is released, same API model for on-premises and Cloud

ARM Definitions and what they mean?

  • Resource – Atomic unit of deployment
  • Resource group – Collection of resources
  • Resource provider – Manages specific kinds of resources
  • Resource type – Specifies the type of resource

Ok, let’s dive into the details of each now.

Resource Group (RG)
Azure Resource Manager

A Resource Group is a Unit of Management providing:

  • Application Life-Cycle Containment – Deployment, update, delete and status
    • You can deploy everything included in a resource group together, thereby maintaining versions of an application along with it’s resources
  • Declarative solution for Deployment – “Config as Code”
    • Resource Group’s are .json, declarative/configuration code
  • Grouping – Metering, billing, quote: applied and rolled up to the group
    • Resource groups provide a logical grouping of resources
  • Consistent Management Layer
    • In the V2 portal, everything is controlled in a RG. RGs can be accessed via REST APIs and resource providers
  • Access Control – Scope for RBAC permissions
    • You can only use RBAC in the new portal and the highest level generally used for RBAC is the resource group level.

But, Rob, that sounds great, but should these resources (VM’s, DB’s, Storage, etc) be in the same Resource Group or in a different one?
Hint:  Do they have common life cycle and management?
Azure Resource Manager
Answer: It’s up to you

Resource Groups Best Practices

  • Tightly coupled containers of multiple resources of similar or different types
    • When resources are in the container, they have a common life cycle. You can deploy these things together, put RBAC on them together with one request and they can know about each other
  • Every resource *must* exist in one and only one resource group
    • Every resource must be in ONE resource group, important for RBAC
  • Resource groups can span regions
    • Don’t have to live in same location, can deploy to multiple regions

A few final thoughts on Resource Groups and their deployment scenarios before we move on.

  • Most significant question is of life-cycle and what to place in a resource group
  • Can apply RBAC, but is this right for a particular resource group?
  • Sometimes resources are shared across multiple applications, in other words a VM could be stored in a storage account in a different resource group
  • Life-cycle is distinct and managed by different people
  • There is no hard and fast rule

Resource Providers

A Resource Provider is used by the Azure Resource Manager to manage distinct types of resources – in your JSON template, you will have code that shows what the resource provider expects to see in order for the resource provider (sitting out in Azure) to build the resource that you want…for example a SQL Server or SQL DB or VM.
Resource providers are an extensibility point allowing new resource providers to be added in a consistent manner as new services are added to Azure – anyone can write their own provider

Resource Provider Types Examples
Azure Resource Manager

Ok, Rob, how do I know what resources providers are available?
Using PowerShell, log in to your Azure account and then run
Get-AzureRmResourceProvider
Azure Resource Manager

Tools typically used with ARM

  • PowerShellBlog Post coming soon
    • PowerShell is used to deploy the ARM templates and can be used to download log files from the Resource Group to analyze issues
  • Troubleshooting in the portal – Blog Post coming soon
  • Visual Studio
    • Although not required, will more than likely be the tool of choice for creating the ARM templates – Blog Post coming soon

Well, that wraps up my blog post on Azure Resource Manager.  We covered a lot and have much more to go.  Stay tuned…..

Until next time, Rob…