wiki

Codit Wiki

Loading information... Please wait.

Codit Blog

Posted on Thursday, March 10, 2016 3:38 PM

Massimo Crippa by Massimo Crippa

With the latest Azure API Management service update, the Git integration has been rolled out. In this post we will see how we can seamlessly control the versions of the proxy configuration and move it between different environments.

Scenario

All the configuration that are applied to the proxy and the portal customizations are stored in a database in the provisioned tenant. Now, every APIM tenants can expose a public Git endpoint to which we can refer to PULL the configuration down to our local (or remote) Git repository.

Once we have our local version, we can apply the changes we need, push it back to the tenant repository and then save it to the APIM database.

In the diagram below, the steps of our scenario

  1. Save (sync from the APIM repository to Tenant Git)
  2. Pull (From Tenant Git to local repo),
  3. Apply changes (on our local repo),
  4. Push (to Tenant Git)
  5. Deploy (from the Tenant Git to the APIM repository)

 

The Git integration is not enabled by default, so first we have to connect to the management portal, go to the Security area and enable the Git access. 

Save and Pull

Next step is to save the proxy configuration to the APIM tenant’s Git repository. This can operation can be done in two different ways:

  • Use the “Save Configuration to Repository” button on the APIM Admin Portal.
  • Call the “Save” operation of the API Management REST API (here how to enable the REST API).

In both cases you have to specify the branch name where to save the configuration and whether to override or not the changes in newer check-ins. This operation can takes a couple of minutes.

Once completed, you can open a Git console and pull the configuration to create a working copy of the remote repository by using the clone command.

Before that you need to get (in the Admin Portal) a temporary password to access to the remote repository.

 

Then run the “git clone https://coditapi.scm.azure-api.net/” command and specify “apim” as username and the temporary password we got at the step before.

Below the folder structure of the local repository. As you can see the proxy configuration is exported (apis, policies, security groups and products) along with the developer portal customizations.

If in the meanwhile a new configuration has been saved in the APIM repo, we can pull it down with the "git pull" command.

Apply a change

Let's imagine we want to change the policy applied to the Echo API to extend the existing basic round robin algorithm.

The policy is applied at API scope so the file to be edited is policies/apis/Echo_API.xml 

This is the result of the "git diff" command after the change.

Now, in order to add the change to the git staging area use the “git add -A” command and then commit the changes with "git commit -m" as in the picture below.

Now we’re ready to push our changes to the Azure API Management Git repo.

Push and deploy

Type “git push” to sync the changes with the repository on our API Management tenant.

The final step is to deploy our configuration from the tenant repository to the APIM proxy.

This can operation can be done in two different ways:

  • Use the “Deploy Repository Configuration” button on the APIM Admin Portal.
  • Call the “Deploy” operation of the API Management REST API (here how to enable the REST API).

For this step I'm going to invoke the Configuration REST API using postman.  Here the details of my API call.

Method : POST
Address : http://{tenantname}.management.azure-api.net/configuration/deploy?api-version=2014-02-14-preview
Headers :
 + Content-Type > application/json
 + Authorization > SharedAccessSignature=....
Body :
    {"branch":"master"}

 

As response I got a 202 (Accepted) and the Location header with the link to the check the status of this transaction.

With the operationResults operation to check the status (Failed, InProgress, Succeded) of the deploy. It's a GET and again we must specify the Authorization header as in the previous call.

If the deploy succeeded, the changes are immediately applied to the proxy. 

Restore a configuration

Now, imagine that you've applied a wrong configuration to the proxy and you want to restore a previous version from your local git repository. For example, these are the timestamps of my configurations:

  • On proxy: updated at 10:22 AM
  • On Teneant Repo: updated at 10:18 AM
  • Local repo: updated at 08:19 AM

I want to discard the 10:18 AM version and replace the 10:22 AM version with the 08:19 AM one. It's a four step procedure. 

A) First thing to do is to bring the tenant repo in sync with the proxy. This step is necessary to mark the proxy as synched. Without the sync you will get this error as result of the the deploy operation : "Deployment operation failed due to invalid data: Snapshot operation is not safe.  Latest sync date: '2015-11-10T10:18:35.5278745'; latest configuration update date: '2015-11-10T10:22:01.7635694'"

B) Apply a modification to the local repo and commit it. This is necessary so the deploy procedure can recognize that there is something to be overwritten. 

C) run the "git push -f origin master" command to overwrite the version in the tenant git.

D) deploy the configuration using the Admin Portal or via REST API

Conclusion

The git integration is a feature that customers have been asking for a while. Now, you can create and manage different versions of your proxy configurations and move them between different environments.

Cheers,

Massimo

Categories: Azure
written by: Massimo Crippa

Posted on Monday, January 25, 2016 10:46 AM

Jonas Van der Biest by Jonas Van der Biest

This blog post describes how you can automatically update your Swagger definition in Azure API Management with TFS Build.

We would like to automate the import Swagger API functionality in Windows Azure API Management management portal. You could to this manually using the following screen:

There are Azure Commandlets for Azure Management API but there is currently a bug. When using the "Import-AzureApiManagementApi" command it is not possible to replace the API definition in Azure API Management  (this is possible in the portal, but not in the PowerShell cmdlet).

But no worries, we can still use REST and invoke the REST API from powershell (as supported in PS 5.0) ourselves.

Enable Rest API

First we will enable REST API on Azure Management Service. Go to API Management, navigate to Security and select "Enable API Management REST API".

Generate an Access Token

Next, generate an Access Token and copy the complete string so we can use it later. Also copy the name of your management API tenant (in upper left corner).

Create the following PowerShell build script and do a check-in on source control

Add a build step to your build definition

Next, we will configure our build and add an extra deploystep to deploy to Azure Management API.

Select a PowerShell script by navigating to Utility

Drag the task just after the Azure Web App Deployment. You might have noticed that there is a sleep of 15 seconds in the PowerShell script. This is because our website will need some time to startup. We could always move the API deployment step a bit further in the build chain but we don't want to have our API and Azure Management API out of sync that long.

Select the script from source control and enter the parameters.

 

The PowerShell parameters are:

-link "link to swagger url" -tenantName "api mgmt tenant name" -sas "shared access key"

And we should get a successful build after queueing a new one.

Wonderful, one step less to worry about when deploying!!

Categories: Azure
written by: Jonas Van der Biest

Posted on Monday, December 21, 2015 9:30 AM

Massimo Crippa by Massimo Crippa

A Successful API is attributed by a well-defined communication of its contents and formats, clear documentation and transparent terms on its usage.
The developer portal is where to collect all this information as a key element to assure a good API adoption, as well as manage the interaction between the developers, giving them insights about the API consumption.
In this post we will see 10 important things to keep in mind to set-up an effective developer portal and some tips about Azure API Management

#1- Explain your offer

Keep it simple, explain the value of your APIs in a clear and compelling way. The home page of the dev portal should provide a clear answer on “what are you offering” without struggling to figure out what the API does. Another question to be answered is about what can be built with the API. Hence also consider the opportunity to create a section dedicated to the use cases.

APIM tip: APIM comes with a full CMS with a high degree of customization. Plan your dev-portal concept and leverage the CMS creating additional pages, sections, custom assets, and introducing different style layers.

#2 - Developer On-boarding

The on-boarding procedure through which a developer gains access to the API must be intuitive and easy. The developers want to be productive quickly and be able to try-out your API in minutes. In order to speed up the on-boarding process, enable different identity providers like Google, Microsoft and Twitter.

APIM tip: If feasible, evaluate to add the possibility to try-out your APIs or part of them without registration. This is a nice to have. I don't want to register and have a key for every API I want to try.

#3 – Getting started

Again, the developer portal is all about to enable the developers to hit the ground running on day one and be productive immediately.

It’s mandatory to provide a tutorial that guides the users through the authentication process and how to perform the API calls via the SDK or directly from code. Those tutorials should be not limited to simple calls and it might cover complete use cases like the “User-Registration” or how the “eCommerce transaction” works. Keep in mind the type of audience and their preferences.  

APIM tip: Create a dedicated page/section and link to this section directly from the home page.

#4 –Add discoverable metadata endpoint(s)

Nowadays there are different formats to describe an API. Swagger (reborn as OADF with the Open API Initiative) is the de-facto standard but others like API blueprint or apiary are emerging.

Publishing metadata endpoints with different formats can help the intake of our API. Consider to use the swagger json as the input for the apitransformer tool to generate api blueprint and raml. The downside is that you have to mantain those different outputs.

Description languages are great integration enablers, but don't forget that the most effective documentation is the one written by humans.

APIM tip: APIM provides the swagger and wadl definition in a secure way via the admin portal. The disadvantage is that we cannot virtualize it to make it discoverable. Consider to download the swagger json file and I re-published it in the dev portal.

#5 - Explain headers

HTTP headers are used for multiple purposes, such as describing the media-type of the exchanged entity, managing the versioning or, for example, as transaction parameter. There are headers that are applicable only for the requests and others only for the responses. Headers that have a generic applicability and headers that are bound to the resource we’re requesting. Standard headers and custom headers.

In this jungle it’s easy to lose your way.

It’s important to describe all the mandatory headers and their applicability, what is mandatory and what is optional, the value that we can expect in the response and how to use it. Use a standardized approach and don't document the same thing multiple times.

APIM tip: create a custom section dedicated to the headers and customize the operation template to create a link to the headers' documentation to accessing the extensive description.

#6 – Explain authorization and authentication

There are several way to implement authentication and authorization in RESTful context.  OpenID connect, basic authentication, shared access key, certificates, asymmetric keys are some examples.

Some of those are implemented using headers, others with different mechanisms.  No matter which type of AuthN/AuthZ you adopted, you should explain in detail the model you are using and how to get the access codes.

APIM tip: It's recommended to have a dedicated section about authentication and authorization.

#7 – Status codes, example of requests and responses.

A proper documentation not only helps to perform the API intake but it's a key factor to retain the developer. Pay attention to enrich the API reference with request and response documentation for all the functionalities you provide.

APIM tip: APIM provides out of the box the possibility to add different status codes with different representations. It’s a matter of configuring and keeping it in sync with your API versions. All this information is displayed on the “Operation details” page.

#8 –SDKs, code samples

The aim is to provide developers the tools to easily connect to your APIs. Code samples and SDKs are the pain-killers for every API intake especially when your API is dealing with complex data structures and binary objects.

On the other hand, building an effective SDK and libraries in multiple languages may require a huge investment, especially for a public API that also targets mobile devices.

APIM tip: APIM provides the code samples to directly invoke the API in different languages. Use the “code samples” template to customize the way the code is generated. Publish all your libraries and SDKs on GitHub. If you’re targeting .NET shop, autorest is a good choice to generate client sdk.

#9 – Support page

The goal is to provide a great developer experience, preventing loss of productivity and customer frustrations. Configure a central point to organize your support service to address the problem right away. The support can be delivered over the phone, with a live chat, a ticket system, social networks and many other ways.

APIM tip: Issue management out of the box can be combined with custom pages to organize other channels (email, social networks, etc)

#10 – Communication and Change log

Attract, engage and retain external Developers, Consumers and the community in the business maturity by establishing an effective and open communication through the API Developer Portal. Provide a tool to discuss your product (and your documentation), provide feedback and feature requests. Create a section to collect the latest news about your API, articles and, last but not the least, to publish the change log.

APIM tip: A blog is a great source to deepen the connection with the developer community. Consider to activate the blog feature and enable the RSS feed to automatic data syndication. Put your documentation on github to facilitate the external contributions. 

Conclusion

It's all about providing a great Developer Experience. Give to your API a compelling front door and boost the API to success!

Cheers,

Massimo

Categories: Azure
written by: Massimo Crippa

Posted on Monday, November 24, 2014 3:50 PM

Massimo Crippa by Massimo Crippa

A successful API is one that is easy to consume, designed to understand the use and prevent misuse. To achieve that, the documentation is crucial. Providing an effective documentation helps to drive the APIs adoption and to reduce the learning curve to perform the API intake in the first place.
Recently we have seen the emergence of new trends to describe and document APIs such as Swagger, RAML and apiblueprint.

Swagger

Swagger is a specification which allows you to layout, describe and then document your API. It's built around JSON to specify API metadata, structure and data models. This results in a language agnostic and machine readable interface which allows both humans and machines to smoothly understand the capabilities of your restful service. Since the version 2.0, the YAML format support has been introduced which makes it even more human readable.

Swagger has a growing developer community and cross-industry participation with a meaningful contribution which is leading to a wide adoption. Beside the specification Swagger has multiple implementations and a rich set of tools which enable you to generate interactive documentation (in sync with the application code), client/server code and potentially to build-up a toolset to help you to build a successful API program.

One of those tools is the built-in swagger-ui , a dependency-free collection of HTML, JavaScript, and CSS assets that takes the swagger API specification as input to visualize and consume your restful API. It’s basically shows the list of APIs (description, version, base path), you can than drill down and see the list of the operations with the http methods,  then the details of every operations, description parameters and return types finally can specify the parameters, try out the API and analyze the response.

ASP.NET

I first tried to add the Swagger documentation to my very basic Web.Api. At the moment Swashbuckle is the best option. Swashbuckle basically looks to the ApiExplorer and generate the swagger JSON self-documentation. It has an embedded version of the swagger-ui and it enables the automatic swagger spec generation simply adding the nuget package to your solution.

The automatically generated specifications are available at this address {baseaddress}/swagger/api-docs and the embedded ui at {baseaddress}/swagger.

The good news here is that Swagger will be integrated in the next version of ASP.NET / Visual Studio (not yet in the 2015 preview) as “confirmed” by Microsoft.
If you're interested to try Swashbuckle, check-out this BlogPost with a detailed step by step guide.

Azure API Management

The Azure API Management allows you to create a new virtual API importing the Swagger or the WADL specification file and this is great. The procedure is straightforward and it’s described here http://azure.microsoft.com/en-us/documentation/articles/api-management-howto-import-api/

From the Swagger ui of the WebApi I created before, I got the JSON of the Characters controller clicking on the “raw” link and I imported it on API management. This is the result along with all the operations. 

After adding the API to a new product and after the publishing the virtual interface is accessible at this address https://coditapi.azure-api.net/bb/APIs/Characters?subscription-key={key}

Azure API Management already have a complete user interface to access to the API documentation and effective built-in console which helps developers to learn how to use the published APIs and speed-up testing. Unfortunately, at the moment the import procedure cannot be used to refresh (or create and swap) a previously created API. This means that the swagger spec cannot be used to keep in sync the virtual API with the backend API preserving the API management settings like security and policies.

Sentinet

Sentinet doesn’t support swagger out of the box so at the moment a possible solution is to introduce a custom implementation leveraging the Sentinet extensibility.

I reached out Andrew Slivker for a comment who confirmed that they’ve already planned to introduce the swagger after the 4.0 release.  I’m thrilled to see the Swagger integration with Sentinet so in the meanwhile I updated my Sentinet demo dashboard to embed the Swagger UI and to link to a swagger specification attached to a virtual REST API I created in Sentinet (or to a public API).

 

Conclusion

Swagger is governable, sharable and readable framework for describing, producing and consuming REST services. No matter which technology you use, no matter which language you prefer, it helps from the professional to the enterprise in the REST adoption that’s why everybody loves Swagger.

 

Cheers,

Massimo

Categories: Azure
written by: Massimo Crippa

Posted on Wednesday, May 14, 2014 4:00 PM

Massimo Crippa by Massimo Crippa

A general overview of the Microsoft Azure API Management that was recently released at MSTechEd North America on May 12th.

On May 12th, at the MStechEd North America, a huge amount of new Azure features have been announced. The Microsoft Azure API Management is one of those.

One of the key points for building a cloud culture is to think of the public cloud as a part of your datacenter. The API Management service allows to take your capabilities (e.g OnPrem Service, Mobile Services,Cloud Services) and build a virtual API and expose it in a controlled manner.

The API Management service can help you :

  • Expose the APIs and share them out with the partners and customers with documentation and samples automatically generated. 
  • Manage and monitor your API program
  • Secure the monitor the access
  • Grow and scale

This blog post gives you a general overview of the service

 

Provisioning

The API management service can be easily provisioned in the Azure portal by choosing App Service / API Management / Create

Next, I chose an instance name, the pricing tier, the Azure subscription and the geography.

Microsoft Azure offers two editions (with different prices) in which you can run your API Management service:

  • Developer.  Mainly for development and test purposes, where HA is not a concern.
  • Standard. You can scale your reserved unit count to handle more traffic.

Then specify:

  • Organization Name. This value will be used in the Developer portal and in the communications to the developers
  • Administrator email. This is the address used for sending the notifications to the developers.

 

When the provisioning is completed (takes about 10 minutes), the new instance appears in the Azure Portal.

 

Administration portal

The admin portal is where to configure and set up the API. To open the portal, click Manage

 

Once authenticated, it opens  the dashboard where you can have a general overview of the published APIs.
Thanks to the "at Glance" view you can easily check the trend, the usage and the health of the APIs.

 

A quick description of the tabs in the main menu:

  • APIs. In this section you create and manage the APIs (url, credentials, operations and caching).
  • Products. A product contains a set of APIs. You can manage the product settings and the product visibility. Developers must subscribe to a product in order to access the APIs it contains. 
  • Policies. You can create and manage your service policy as a set of pre-built policy statements. A policy can be applied at different scopes (Product, API or Operation).
  • Analytics. A set of reports about Usage (nr of calls, bandwith ), Health (different views per StatusCode, ResponseTime) and Activity (different views per Developer, API, Products).
  • Developers. Add, remove or block users.
  • Groups. Allows you to choose which roles are able to see the product on the developer portal and subscribe to the product.
  • Notifications. Manage the communications witht the developers as subscription request, subscription quota limit, etc.
  • Applications. Allows you to manage the applications published by the developers.
  • Security. Developers can create logins to the developer portal by using a 3rd party identity provider as Twitter,Facebook, etc.

Developer portal

The developer portal gives the access to the published APIs and products. The automatically generated documentation and the built-in console helps developers to learn how to use the published APIs and speed-up testing.

In order to gain the access to the APIs, the developer must subscribe to a product. Once the subscription is approved, the keys will be listed in the user profile area.  

 

You can then easily invoke the API using the built-in console.

and analyze the result in a nice UI. 

 

You can find the documentation and step by step tutorial at this link http://azure.microsoft.com/en-us/documentation/services/api-management/

 

Cheers,

Massimo

Categories: Azure
written by: Massimo Crippa