Akshay Ranganath

I ♥ APIs City Tour, New York by Apigee

Blog Post created by Akshay Ranganath Employee on Jun 25, 2015
Develop APIs that developer love. Great tips in this ebook.


On Tuesday, June 23rd, Apigee conducted a session called " I ♥ APIs City Tour, New York". I guess it is meant to be both an educational session to interested folks about API and a build up for the October conference in San Jose. I was quite impressed with the sessions that were conducted and came away pleasantly surprised that it was actually a session that had a lot about APIs and their importance rather marketing about Apigee.


Here's a brief summary of my take-aways from the sessions at New York.


Thinking About APIs

The first session spoke about the need for APIs. It was a very interesting session John Rethans started with a long story about how the modern day city of Barcelona evolved. In the middle ages, this was a small trading town, protected by thick walls for security. When the city had to grow, the walls had to come down. The city had to grow in a manageable fashion and yet integrate with the old city. To this purpose, the founding fathers  planned a grid system with each building taking on one of the 30 or so building blocks. Their vision was that each citizen was entitled to sunlight, greenery, and clean living (sewage, drinking water). Within these constraints, the city was free to grow.


The old city is pretty much like the core business systems in an organization. These are things that are hard to change and yet hold the history and culture of the organization. Walls around it will not work and needs to be opened up with APIs. They should be designed so that developers like it and yet not expose more information that required. The analogy of building a city to API was quite an interesting take.


APIs & Apps

The next few sessions focused on the importance of Apps and the growing market of mobile and smart devices. Apigee's take on apps:

  • apps are the dominant mode of interaction
  • analytics enable adaptive experience
  • APIs enable agile execution at pace

Essentially, the legacy and core systems are "systems of record". They need to have an API layer that can allow for quick combination to build various services that can be consume by things that nobody can plan for. As long as there is a way to interact and the rules of interaction is well documented, an organization can support the current apps, tomorrow's internet of things and whatever comes day-after-tomorrow.


Bottom line: Start thinking about API as a corporate asset and give it the care it needs!


Building blocks of APIs

The best tech sessions were by Greg Brail, Chief Architect. He spoke about the concept of API in that it is a connector or it is a contract. The reason (ReST) APIs are so good is that they are based on known established web standards:

  1. HTTP(S)
  2. JSON
  3. oAuth
  4. Nothing else

If an API vendor were to ask for anything other than these, it would not be a good API setup.


Speaking of pervasiveness of APIs, he pointed out that we tend to think of APIs as the calls we make to EC2, or to a website starting with api.*. However, APIs are like an iceberg where 90% of them are invisible. They would be either internal calls, never exposed to public. Or they could be calls that are not perceived as API by humans - like a thermostat talking to alarm system, a car's music system talking to mobile phone and so on.


API Best Practices

In this session, Greg Brail covered the details on what makes an API good. His advise was simple. Design APIs that developers love! To this end, he spoke of about 5 important things:

  1. API website: Generally named as "developer.customer.com". This site should be open and with no authentication and paywalls. API calls themselves can be protected Glad that Akamai's {OPEN} site is developer.akamai.com.
  2. Developer self service: The website should have easy to read documentation, examples and code snippets to help the developer get started.
  3. Documentation: More in-depth documentation on each call, the inputs and outputs, as PDF and HTML.
  4. Live testing of API: An interactive console to "play-out" the API and see its behavior live.
  5. SDKs: For complex environments like iOS development, Android, an SDK to work with the APIs would help since it would save time and increase adoption.
  6. No friction sign up to developer site and community

Finally, he referred us to the resources section of Apigee site that has a lot of resource on API design and development.


What next?

After the session, I was quite impressed and read through this wonderfully written 32 page eBook called "Web API Design - Crafting Interfaces that developers love". It is very readable and extremely pragmatic in approach. So do take time and read through it! It will be well worth the time.


Other tidbits

The meeting was held at the NASDAQ building. I went in with high hopes of seeing a lot of buzz, milling stock brokers and was completely let down :-( Since everything is online, the NASDAQ building.

There was one session that was very Apigee focused. It was on Apigee Edge, the cloud deployment of the API platform by Apigee. I had gone in to the meeting thinking that this sounded just like Akamai - a system that was reverse proxying the real thing. However, I was surprised at the amount of functionality that is platform provided by the platform. It offers a capability to modify request and response on the fly; manipulate responses using pre-canned operations or with custom Javascript or even a node.js implementation. To top it off, the UI would allow drag-and-drop of functionality like caching to various stages of the request-response-response manipulation cycle. It was quite impressive!

Finally, there were a lot of business oriented sessions as well. The issue of getting a buy-in, the difficulty in transitioning to an open culture and opening API as an organizational paradigm was covered. There was a fireside chat as well with Mapquest, NASDAQ and FirstData that covered some interesting challenges on adopting the API culture.

These sessions were interesting for business / leadership teams that were looking for answers on digital transformation.