Now that the Nordic APIs World Tour is finished, let’s circle back to sum up what we learned. During our tour, expert API practitioners shared their insights with attendees at 4 cities, touching on API development, security, design, operations, and more during intimate conference settings.

A recurring theme in many talks was API Design. So, in this article, we’ll sum up important API design lessons that were conveyed by our speakers — both practical tips on technical implementation, as well as more more philosophical considerations on how to hide (or not hide) complexity when designing an API.

1: Know Your API Requirements

API design should not begin with technical documentation, but should rather originate from your fundamental goals. Knowing what your API needs to accomplish is of the highest importance. This is defined in the analysis phase of the API lifecycle.

As Phillipp Schöne from Axway pointed out, API designers should ask “how APIs can support the business function and not how they can support the needs of IT.”

2: Think of APIs as Building Blocks

It’s important to remember the unique characteristics of APIs. As a consumer, tying into a service’s underlying data or functionality is inherently a unique process. Though comparable to SaaS products, Andreas Krohn from Dopter highlights two key differences:

The first is that APIs are building blocks and not finished products: “If somebody is using your API they are basically outsourcing a part of their business to you”.

His second lesson is that machines are not flexible. If a SaaS product changes, a person can adapt, but if an API changes, a machine is not as adaptable. This influences the design and the whole lifecycle of the API, and affects how we prepare for parameter changes and versioning.

3: Understand Your Audience

Developers are unique consumers in that they come with a handful of specific considerations. During his talk, Bill Doerrfeld reccomends API hosts to treat their platform as a product, with a primary concern being assembling a comprehensive demographic analysis. Knowing who your target developer is can refine both API functionality and segment future marketing attempts.

The need to understand your audience is just as applicable during an API’s Operations stage. If you are updating, versioning, or performing major redesigns on an existing API, you need to carefully respond to the feedback from your users to make the new version as good as possible.

Marjukka Niinioja, Senior Consultant and Manager at PlanMill shares her experience with leveraging user feedback during a major redesign: developing PlanMill’s new RESTful API, UI, and back-end architecture.

PlanMill payed close attention to the feedback they were receiving internally, noticing three main recurring points:

1. The API was too complex for the developers to use.
2. The documentation was not sufficient.
3. The error handling needed work.

Using this feedback, and by testing and consuming the API themselves, the PlanMill team was able to hone in on important aspects to consider during redeployment. The takeaway is that if you are redesigning an API, you are poised to release killer API improvements — as you already have real world data on how API functionality is used, which can be repurposed to improve efficiency and overall API user experience.

4: Decrease Confusion For The User, Let Provider Handle Complexity

Who pays the price for complexity? Nordic APIs veteran Ronnie Mitra of API Academy argues that complexity is necessary — what should be avoided instead is confusion. Mitra contends “it is a designers job to reduce confusion and embrace complexity in their business domain.”

There has been a move toward simpler products and simpler interface designs. Mitra, an expert in developer experience and API design, advocates for smartly designed software and APIs that retain simplicity but also cater to complex requirements. Quoting John Maeda’s Laws of Simplicity, Mitra notes that “Simplicity is about subtracting the obvious and adding the meaningful.”

A steering wheel in a F1 car is very complex compared to the steering wheel of a normal car, “designed and optimised for its user and the situation”. Ronnie makes a great point that “every design decision is a decision of if you [as an API provider] or client app developers will pay the price of complexity”. As an example, OAuth is complex to implement by the service provider but easy to use by the client developer. We cannot avoid complexity, but we can architect our APIs so that the user-facing side is deceptively simple.

Ross Garrett from Axway also talks about what applying an API-first strategy means for enterprise organizations. In dealing with legacy systems, he notes that a missmash of tangled infrastructure can be masked by using proper API management tactics.

“Your old architecture [may not have] useful APIs, or may be older SOAP services that don’t perform well in the context of mobility or cloud integration. Some legacy things need to remain, but API management can extend and reuse by translating all old interfaces”

What’s important is having a clean business appearance for the end user.

5: Use Hypermedia For Evolvability

It is impossible to talk about API design without mentioning Hypermedia, a subject that came up in several presentations during the Nordic APIs World Tour 2015. Pedro Felix of Lisbon Polytechnic Institute, offers a deep dive into HTTP. He summarizes his presentation about API design this way:

“if you have a problem, keep calm and look for an HTTP RFC”

Pedro considers hypermedia as the key factor for evolvability, allowing API providers to react to new business requirements quickly without breaking client applications. Related to Mitra’s theory on the distribution of complexity, using hypermedia means more initial complexity for client app developers, but an overall reduced complexity considering the ease of future changes.

6: Learn From Real World Information Design

Brian Mulloy from Apigee demoes a hypermedia API for the Internet of Things. By using hypermedia it is easy to introduce new devices into the IoT since all possible states, actions and feeds are described in the API itself.

Mulloy describes API design for the Internet of Things as using information design for physical objects. He compared this to the early days of mass car production in his hometown Detroit. Suddenly the city had lots of cars, but infrastructure was not prepared for a large automobile influx. The resulting confusion lead to chaos and even a large number of traffic related deaths.

The solution was to use information design that resulted in standard designs used all over the world today. Pedestrian crossings, traffic lights, stop signs, and lane markers make it clear how to behave in traffic. Akin to the early days of cars, we are still working on how to organize and design today’s APIs for the IoT.

7: API Design Needs To Convince the Architect

Having a shared vision within an organization is key for API interconnectivity to be accepted. To help convince API naysayers, whether they be architects or engineers, in his talk, Adam Duvander of Orchestrate walks through four ways API providers can frame their API product to foster confident adoption. These factors should be considered when designing an API in order to respond to common stigma associated with API integrations.

1. The architect wants control: Accustomed to traditional methods of infrastructure — data storage on local servers — the architect may be opposed to cloud operations, desiring to ‘touch’ the software. To workaround this stigma, API providers can offer the ability to download and store data sets locally, or even offer an on premise, dedicated, managed option the API.
2. The architect wants zero downtime: To foster reliability in the service, having transparent developer-facing logs that communicate API uptime is critical. Quality examples are the Stripe system status and live twitter feed, which allow transparent and helpful status updates on downtime. Others to model are Facebook, Twilio, and Github.
3. The architect wants to see responsibility: API systems need to be designed as secure systems using modern approaches. From a process oriented perspective, DuVander notes that providers need to be very clear with what types of data they are able to access. Share best practices with developers. A good model is Bit.ly — they make licensing clear, sharing security best practices on a dedicated channel.
4. The architect requires an integration that guarantees longevity: With public APIs falling off the map from both small and large players, architects have a good reason to be skeptical. DuVander recommends that API providers clearly understand and communicate their monetization model, and demonstrate to consumers that their situation guarantees longevity. According to Duvander, when it comes down to it, “worrying about API longevity is just another way to ask for more control”

Summarizing API Design Points

As an API has two users — the human developer and the machine client — designing can be a bit tricky. By analyzing feedback from developers we can design better APIs for them, and by using proper techniques we can assure that APIs are designed for efficient machine consumption.

By using the lessons learned from the Nordic APIs World Tour you can design an API that allows an API provider to handle most of the complexity, and simplify processes for your client application developers. Above all, do not forget that the API design should serve your overall business requirements.