‹/› Devsworld News

Devsworld Home

Making Your APIs Easy to Use

By Peter Bernstein
July 12, 2016

It is not exactly a secret that in the software-centric, always on/all ways connected and real-time world that having the ability to be responsive is a top priority.  It is why DevOps has become so mission critical to organizations regardless of their size and location. 

We live in what is called by many the NOW Economy. It is an economy where change and the speed at which it is accelerating are the only constants.  Hence, giving developers the best tools to easily, quickly and securely create, launch and scale new applications and services is crucial.  And, the tools of choice for facilitating the need for speed and accommodation to change are applications program interfaces (APIs).  In short, the future really is all about the APIs as we move into not just a Now Economy but an API-centric one.

A great place to get up to speed on the impact APIs can and will have going forward is at the All About the API event taking place July 19-21 at Caesars Palace, Las Vegas.  Attendees will be able to hear subject matter experts that are creating this future and how they are leveraging APIs to create sustainable competitive advantage for their organizations, have hands on training and the opportunity to interact with colleagues.

As prelude to All About the API, we asked one of our featured speakers, Michael Stowe, Developer Relations Manager, Mulesoft to share his views on not only the importance of APIs and why we are moving so quickly to an API-centric economy, but also the critical tasks of making your API easy to use. 

Devsworld:  What new business opportunities are being driven by to the growth of the so-called API economy?

Stowe:  The API economy has created an opportunity for extremely fast-paced innovation, making it possible for one-person startups to build fully featured applications that can rival some of the larger enterprises.  This rapid change, as well as the growth of API consumers (web applications, mobile devices, wearables, AR/VR and smart devices/ IoT) has also changed the way consumers are demanding services and data – making the ability to adapt architectures at the same speed as technology an absolute must.

It is perhaps the first time that we’ve seen large enterprises and startups competing fairly in the same space.

Devsworld:  Is there a market for APIs you would consider the low-hanging fruit?  Which markets are the next to leverage APIs extensively?

Stowe:   The low hanging fruit in my opinion is within the enterprise space, where many companies find themselves relying on large, but archaic monolithic systems.  These systems that have worked exceptionally well over the last several decades are now facing demands they were never intended for.  The API revolution is requiring companies to pursue a more microservice style ideology, moving away from centralized (but overloaded) IT and more into line of business developers through the use of API-led connectivity and application networks.

As for leveraging APIs, I’m a believer in that the revolution has just begun.  While APIs are quickly becoming interwoven into everything we do, I think we’ll see rapid expansion into everyday products, going beyond just simple TV applications more towards Siri/Alexa style devices.  Add advancements in AR and robotics, and I think over the next decade we’ll see APIs completely revolutionize every aspect of our lives.

Devsworld:  What are the major challenges API developers face?

Stowe:   Developers are great at developing, but we struggle with tunnel vision.  We often create applications for today, not for tomorrow.  Or as I like to point out, very few developers look at code they wrote several months ago and think “this is great.” 

The problem with APIs is that they are a contract, and a strong interface.  This means that we have to create something that lasts not just months, or a year… but years.  Something that can be flexible enough to change and evolve without breaking the contract/interface.  Or if you go back to the code example, it’s like changing an interface that has thousands of classes depending on it.  Every one of those classes break, and creates a tremendous amount of work – except that these classes are businesses and developers depending on your API’s interface and consistency.

This is also compounded by our lack of understanding when it comes to HATEOAS, and the lack of utilization of code (or code-on-demand as specified in Fielding’s dissertation).  This makes our APIs rather rigid and unbending, meaning that when we do have backwards incompatible changes often times our only choice is to break that interface and version our API (a very expensive endeavor).

To add to the complexity, it’s not just building an API that will last, but an API that makes sense to your consumers and meets their needs.  While often not the developers fault, this is more often overlooked than I would like to admit.  And often we create APIs that actually don’t truly solve the problem our consumers are facing.

So to recap, API design, API design and API design is in my opinion the greatest challenge developers face today.  Thankfully, we’ve also seen huge advancements in the technologies designed to help us with just this – such as RAML an API modeling language that lets you quickly design and prototype your API in a human-readable format with no programming required.  The nice thing about these specifications is that they are also reusable for building, testing, documenting and sharing your API.

Devsworld:  Who, within an organization, should businesses target when marketing their APIs (i.e., business leaders, C-Suite, developers)?

Stowe:  This really depends on your API, and who your target market is.  At all times developers will be the consumers or “customers” of your API, so you do have to cater to their needs – such as providing a good developer portal with easy to understand API documentation, interactive consoles, code samples and walk-throughs at a minimum.­

But while you have to cater to developers, that doesn’t mean that you should be marketing your API towards them.  Again, that depends on who your target market is, or who the business decision maker is.  For smaller APIs this will often be the developers themselves, but for large enterprises or financial institutions the rules completely change, and the API must be carefully vetted while receiving cost center approvals.

Devsworld:  How do you measure ROI of APIs?

Stowe:  Similar to the last question, this strongly depends on what your API does, and how you setup your API model.  For example, if you’re a SaaS provider trying to build partners and extensions to your platform – you may gauge the success of the API by the number of new customers brought in through third-party platforms, or customer retention of those using third-party services with your platform vs. those who are not.

One of the challenges is many developer relations teams who are in charge of marketing the API get stuck on what I refer to as vanity metrics, such as API users, calls, etc.  While indicative of the great work they are doing to acquire and nurture developers, there is no real dollar value that can be tied back to these numbers alone, meaning that they essentially become meaningless in the overall conversations.

The important thing is to again understand how the API will impact your business’ bottom line, and then base your metrics on numbers that you can tie directly back to those dollar figures.

Devsworld:  Who is responsible for security?  Is API security more challenging that securing other applications, hardware and networks?

Stowe:  Whenever you’re dealing with security, you’re dealing with layers.  To say that one person is responsible for security is a substantial misnomer.  The first line of defense when it comes to security is your architect (in how the API is designed and architected), followed by your developers who are actually writing the code.

APIs like web applications (or any public application) are difficult to secure, as there can be a number of ways a hacker might attempt to breach them.  But one of the greatest dangers is developers underestimating these dangers because they are dealing with “strict” formats such as JSON or XML.  Oftentimes I see developers forgetting to validate and sanitize this data, instead using just a decode mechanism to see if it’s valid or not. 

This does not eliminate many of the threats such as SQL injection, XSS (for SaaS applications), or memory based attacks using the JSON/ XML itself (through numerous nesting).

Of course, there are server concerns as well, bringing in DevOps.  The server needs to be constantly monitored and patched – as a breach in your API architecture not only creates vulnerabilities for yourself, but also your consumers.

Finally, every API should live behind an API management system, or gateway that serves as proxy to your API to prevent many of these malicious attacks from ever reaching your server in the first place.  But even the best API Manager cannot protect against 100% of all attacks, which is again why when we talk about security, we’re talking about layers and taking steps at each component of the architecture to make it as secure as possible.

Devsworld:  Which is better, SOAP or REST?  Why?

Stowe:  A lot of people want to jump on this, but again we have to take a step back to understand who your customers are, and what your needs are.  For example, if you’re dealing with enterprise customers with legacy systems – they will most likely be more familiar and better setup to support SOAP than a modern-style REST API.  Or if you need to be able to track state or have the capacity for transactions, SOAP is most likely a better alternative to pure REST. That’s not to say you can’t do some workarounds with a REST API to accommodate these needs, but by its nature REST is stateless (meaning the server does not store the state of the clients calls).

With that said, REST offers many advantages over SOAP, and provides a simpler interface with more flexibility.  For this reason I would suggest that anyone building a new API carefully take a look at REST, but also weigh what your needs are.

What’s more important than picking REST or SOAP, is understanding why you picked that format, and WHAT that format actually is.  Too many developers pick one or the other, and then slowly start trying to convert it to the other because they do not understand the constraints or limitations of the API they are building.  Not only will that create an API that is far more difficult for your consumers to use, but it will also greatly decrease the lifespan of your API.

Devsworld:  How often are APIs changed or updated?  How is this accomplished while ensuring minimal disruption to users and their customers?

Stowe:  Your API is a contract.  With that said, contracts are amended all the time – it’s just important that it’s not broken.  This means that you can certainly “change” your API in terms of adding new resources, more data, etc.  But you should not break your API by removing resources, removing data or changing the requirements of calls.

Not unless you have built a truly RESTful API taking advantage of hypermedia and code-on-demand so that all changes are automatically negated by the client’s ability to adapt on the fly.

For this reason, when building and maintaining your API, you should look at versioning as a necessary evil.  There are times you will absolutely need to version, but this should be limited to you drastically changing your platform (the actual workflow of your service, not the underlying technologies which should be abstracted anyways by the API), you need to modify your API format (going from SOAP to REST) or your API failed (which is what we want to avoid in the first place).

This, again, is where an API modeling specification such as RAML can play a critical role, helping you understand your API design, ensure consistency and see the impact of your changes before implementing them into the source code and pushing to production.

Devsworld:  What kind of standardization is still needed to drive successful mass development and adoption of APIs across verticals?

Stowe:  Two areas we are still very much struggling with are hypermedia and code-on-demand.  These have led to the development of alternative API styles such as GraphQL over RPC.  However, once we start finding ways to better implement HATEAOS and code-on-demand, it opens the doors for universal API clients and smart clients (substantially decreasing the implementation process as well as maintenance required).  It also opens the door for newer innovations, such as API-chaining which removes the need for numerous calls or model-style query languages (which, while offer a nice convenience layer, more tightly couple the client to the server’s underlying data models).

Devsworld:  How important is building an ecosystem around your API(s)?  Can your API(s) be successful without it?

Stowe:  This really depends on what we mean by “ecosystem.”  If you mean a thriving developer community that sings the praises of your API, then the answer may be no.  It really depends again on your business model, and how you generate revenue/ who the decision maker is.

But, having a strong API ecosystem also drives revenue, and encourages developers (and thus their companies) to use your API.  Strong API ecosystems also often result in better documented APIs, simpler onboarding and better support (often driven by the community itself).  These will all be things your consumers will evaluate when choosing whether or not to use your API or your competitors.  If they can get the same content or services, at a relatively close price – this is often the tie breaker.

And, if your target market is developers, and you do not have a strong ecosystem/ are not working on building on… good luck!

Devsworld:  What differentiates one ecosystem from another?

Stowe:  I think I just found the topic for my next book (again depending on what you mean by ecosystem).  At the core, all ecosystems are very similar – but they evolve into their own cultures, with their own unique styles and resources.  So while every ecosystem is the same, they are also very, very different.

Oftentimes this comes from the tone of the company, and the tone of those reaching out the developer community.  Based on their tone, the community attracts those with similar ideologies, creating what really becomes a reflection of a company’s leadership. 

That’s another great way to phrase the question, what differentiates one company from another.  Because in the end, I think you’ll find the answer becomes the same.

Devsworld:  Why should attendees at All About the API make sure to attend your session/booth?

Stowe:   I’ll be giving two different talks, both that focus on the key aspects of the API lifecycle, as well as the real world and quite common traps developers and companies fall into when designing and developing APIs (and how to avoid).  These talks will also jump into some of the tougher areas of APIs, or less understood components such as Hypermedia, while taking a practical approach to implementing them while also covering API best practices, modern techniques and common or defined standards.

Of course, if you’re not able to attend my talk, much of this is also covered in my book, Undisturbed REST: a Guide to Designing the Perfect API which can be downloaded freely at http://mulesoft.com/restbook.  However, the talks will go a little bit more in-depth, and also provide an opportunity for Q&A both on the topics covered, as well as other topics of interest/ real-world problems.

Then again, there will be a lot of great talks, so if the above doesn’t convince you, I promise to throw a pun or two in as well.  And if that’s not enough, please still find me and say hi!

Hope to see you at All About the API July 19-21!

About the Speaker

Author of Undisturbed REST, Michael Stowe is a regular API conference speaker and consultant. An active advocate for creating better APIs more efficiently, his work has also been featured on ProgrammableWeb, DZone, and InfoQ among others.  When he’s not talking APIs, Michael works as MuleSoft’s Developer Relations Manager, helping developers and enterprises alike transform their businesses with API-led connectivity and application networks.  You can view his past talks and slides at http://www.mikestowe.com/slidesand follow him on Twitter @mikegstowe.

Edited by Alicia Young
Related Articles

Telecom API Market Set for Big Gains

By: Steve Anderson    3/24/2017

A rapidly increasing need for APIs and similar measures is expected to drive big gains in this market through 2021.

Read More

Flowroute to Discuss Common API Mistakes at All About the API

By: Alicia Young    2/8/2017

Doug Waller of Flowroute will be taking part in a panel at the All About The API event, collocated with ITEXPO, to discuss common mistakes that occur …

Read More

Wear Your Lifestyle with Google's Awareness API

By: Alicia Young    2/8/2017

Google has teamed up with H&M's digital fashion house Ivyrevel to use its Awareness API in a unique way. The duo wants to digitally design customized …

Read More

10 Trends that Will Impact Open-Source Technology

By: Special Guest    2/8/2017

Open source has become an integral piece of every developer's arsenal. The power of the community, the wisdom of many, and the ability to hook into va…

Read More

What the Google Hangouts API Shutdown Means

By: Special Guest    2/6/2017

Google's in an interesting place with Hangouts and chat with both the enterprise and the consumer. One thing is clear - what it's doing with Hangouts …

Read More