The API Developer Experience

3 myths, 3 suggestions, 3 facts

We’re moving toward a world where we're getting to know our devices better. We're talking to them and they are talking to us, we are exchanging information. We have never felt this close to our devices, they have never felt this personal. From health monitors to drones, thermostats to smartphones; we are enjoying every bit of what they add to our lives.

More and more devices will be added to our lives; with an ambition of enriching life's quality. While this is great from a technology and consumer standpoint, it poses a big challenge for us - the IT folks. One side we have this complex IT system landscape and on the other side the numerous devices to be served. How do we cope with this complexity? APIs can help bridge the gap between IT systems and devices.

Let us take a look at the API Value Chain. An API exposes a business asset. This API is consumed by one or more Apps. And it is through these Apps, the end customer experiences your services.

Figure 1 - API Value Chain

It is fairly obvious that these apps are crucial in not only bringing value to the end customer but also to the success of your API. Yet, the Developer who builds these beautiful apps is often neglected when it comes to building APIs.

I'd like to highlight 3 common myths in teams building APIs:

• Myth 1: We'll think about the developer experience later. It's for public APIs anyway.
• Myth 2: Developers are bound to love our API. I mean, what's not to like?
• Myth 3: We know what's best for our API. We don't need developers telling us what to do.

An attitude like this won’t get you far. With more than 12000 public APIs (on the Programmable Web) to choose from, your API will be like a great film in whom no one is interested. The purpose of this article is to give a different perspective that will help you build APIs loved by Developers.

Suggestion 1: Treat your API as a Product

An API is not just a software interface. It is an interface to your business asset, your services, your organization. It should be easy to consume and build beautiful apps with. Hence, treat it like a product and do whatever it takes to make that product a success.

For example

• Give your API a URL; make it discoverable. If it is a public API, register it at http://apis.io/
• Have clear Terms of Service (TOS). Do not leave these up to the Legal Department to write down. It is your product. Write them down yourself.
• Ensure easy sign up. There is nothing worse than a hundred clicks just to get an API key.
• Document your API thoroughly. Documentation, though under-rated is read by anyone who wants to consume your product. Make sure the documentation up to date.
• Software Development Kits (SDKs) are great to have people develop on your API.
• Make it easy for developers to write apps with your API. Provide Hello World sample apps.
• Announce releases and have release notes.
• Provide Sandboxes for developers to test and play with your API.
• Honor feedback and provide support. 

Suggestion 2: Ensure ease of use

An API that is not easy to use will most certainly not be used. Make an effort to keep it intuitive for an App Developer. Remember that an App Developer may not always understand your business.

For example

• REST is best; don’t make up your own conventions.
• Stick to JSON for representing data. JSON is by far the most popular representation for JavaScript based clients.
• Use HTTP; and all of it (status codes, verbs and all). Do not design your own standards.
• Use Hypermedia to enhance navigability of your API. If the data is the state, hypermedia is the state transfer. Both aspects are equally important when it comes to a great API.
• Use OAuth 2 for authentication.
• Provide curl Scripts to access and explore your API.
• Think about different types of clients that might use your API. Mobile clients, screen-less clients.
• Never break existing clients. Never make breaking changes.
• A great API knows its audience. Do not expose internal jargon.

Suggestion 3: Welcome Innovation

Creating an API for a specific client and for a specific need may be a good starting point, but it’s certainly not the destination. Dream big! A great API has immense potential. To tap this potential, you need to welcome innovation. This innovation will most likely with come from the consumers of your API.

For example

• Developers are not stupid. Get to know them.
• Invite feedback. Use it as a boost to enhance your API.
• Organize Hackathons with your consumers. Together, special things happen.

I sincerely hope that you will take these suggestions into consideration when you build your next API. I’d like to conclude this article with the 3 facts which serve as a reminder that an API is more than just a software interface.

• Fact 1: An API is only as valuable as the Apps built with it.
• Fact 2: This makes the API Developer Experience crucial.
• Fact 3: Like any good experience, the API Developer Experience must be designed.

A great man once said, “Design is not just what it looks like. Design is how it works”. So Design like you give a Damn! Design like you give a Damn. Design like you give a Damn.

Hypermedia is the door of your API

In my interactions with people on designing and building APIs, Hypermedia has always been the most difficult to get across. I've tried explaining it from different perspectives and here's the one that stuck. After using this on 50+ people, it's time for spreading the message.

The metaphor: "Hypermedia is the door of your API". 
An API without Hypermedia is like a room without doors. When one is in this room, one can admire its furnishings, the color of the walls, the curtains, the paintings, the lovely view outside or maybe even the carpet and plants. In short, one can appreciate the beauty of the room. And that's pretty much there's to it.
Hypermedia is the door. And it's through doors that you get places. It's the doors that allow you to explore the world beyond the room. And because the room was so beautiful, the door holds a lot of promise. A promise to something magical. Hypermedia essentially is the link to this magical space which can now be explored.

The following image helps me remember this promise of Hypermedia

I'm a developer

Gone are the days when you could introduce yourself as Java developer, .NET developer or even the more generic Front-end developer or Backend developer. Organisations are looking for folks who are flexible and willing to learn and unlearn. This counts for developers as well. Getting wired to a certain language or technology only makes you stagnant. You often fail to explore and embrace change and new technologies.

Hence I like to call myself a 'developer'. Simple, elegant and yet powerful!

My CV already reflects this. In a short period of under a decade, I've coded in Java, C, C++, Groovy and EGL. And who knows what's in store next. All I know is that software development is really cool and satisfying, and I'd want to continue doing it. Not prefixing the language to the title gives the freedom to explore and embrace the new. And that's fascinating!

I'm Flavia and I'm a developer. So what's your title?

Goodbye mails, moments

Saying goodbye is one of the most difficult things. And yet you know that it's a change which ought to happen. Someone said "I'm a passenger, and I ride and I ride" which is so apt to everything including life itself. Change brings new opportunities, new ideas, new lessons.

I'm in the middle of switching jobs and have said my goodbyes in person to many people I knew.  But writing a goodbye mail is particularly difficult; how do you put a decade of your life in one e-mail taking care it covers all the things you want to say and yet remain short enough for people to read it fully. I took my time: after couple of drafts, I had a copy which was ready to be shipped. The subject of the e-mail reflected my re-ignited admiration to the unix language. Got a number of replies and answering them as I write this post ....

Pleasures of the notice period

A notice period is the period between submitting your resignation and the last day at the job. In my case, the notice period is 2 months. Though it seemed pretty long at first, I must say it's needed or that I needed it; especially when you're trying to end almost a decade of your career. Therefore this dedicated blogpost!

At first I thought that this period would bring with it mixed feelings. On the contrary, those feelings have been only that of joy. It gives you the opportunity to look back at all those years; ponder on the memories, experiences and most of all - the people you've come in contact with. For me, it's that people factor that has brought the joy. I've been taking the time to talk to most people who've been a part of my life at my current job and during all of those conversations not only have I renewed my contact with the person but genuinely learnt more about him/her and created a deeper bond. These conversations are nothing like the many we've had in the past years. They bring something new - they're about motivation, passion and all of those things that makes you wanna work in this field.

My most cherished format has been the one-to-one lunches. And I have had many! Dinners and drinks reach a broader audience but aint as personal. Although I look forward to each of those moments. With less than a month to go and couple of evenings & lunches planned, I hope to bundle the last decade and store it in a very special place in my mind.

MacGyver and the A-Team

I have used this approach to successfully and sustain-ably implement the REST architecture. Yes, this blogpost is still about software development! The credit for coining these terms go to Ron Kersic.

Couple of years back we began with a new architecture implementation that involved RESTful services. As with most new things, the details were missing. The vision was clear - RESTify. But the mission and how to get there - NOT!
We chose for the Macgyver - A-Team approach to rescue us.

MacGyver phase
 
How this works is real simple. MacGyver, as most people know is someone who only needs a swiss army knife to put his scientific knowledge into action. For those who are from my generation and later could read up on this character here.
The MacGyvers in our case were a team of 5 persons; belonging to different specializations from an architecture point of view. I was the Design MacGyver. We set out making an inventory of stuff that is being handled by the current architecture and stuff that needs to be handled by the new, RESTful architecture. This was by no means a complete list but just items which required immediate attention to get a setup going. We worked out the items in proof-of-concepts and got a working bit going. What's important here to note is that the solution was not as polished and refined as it needs to be, but we got stuff up and running! This took couple of months (2 hours a day to be exact).

A-team phase

Once all the items in the list were tackled, the A-team was formed. This team consisted of stakeholders from all aspects of interest in an architecture (design, development, infrastructure, domain knowledge). Lot of people overlapped but new ones joined as well. The A-team worked on getting stuff refined created by MacGyver. They worked on getting stuff documented (standards, guidelines, etc.). They worked on proclaiming the knowledge using training, workshops.

Looking back
The MacGyver still exists. He is available on demand when something needs architectural attention. He happily does his swiss knife magic. The A-team helps in the refinement and the broadcast of the message. The project teams use the principles and work towards finishing the product. An emergent architecture setup!

I can't stress on it enough - it is crucial to get stuff working and get immediate feedback before it's rolled out to the mass. The MacGyver - A-Team approach addresses exactly this and am very happy to have discovered it.

2 years of doing Gamification

Last two years I've been involved in initiating and implementing Gamification. And what a learning experience it has already been! It all started with a simple problem. After leading a group of developers for couple of years, I noticed that we could use more binding as a group. This was difficult to achieve given the fact that we were placed at different locations and worked for different customers. The feedback from the group made this problem very clear and I set out in search to address this problem. I remembered the TED talk from Gabe Zichermann where he talked about games providing engagement. And I thought: let's try and see if it really works.

With a small core team, we designed a game; very custom-made, fit-for-use for our group. The design and implementation of the game kept the core team engaged and the rest of the development community liked the fun aspect of it. But stuff like this doesn't remain hidden. Soon people from the rest of the organisation found out and before we knew it, the game was rolled out to the whole of our Netherlands business unit.

The game is simple and revolves around badges like most gamification projects. But what makes it special is that customization. It is tailor-made. We introduced events to go with the game - pure gamification events! They are fun and bring people from all over the organisation together. We created a game we wanted to play!

After 2 years, we are now a Gamification special interest group which attracts people from all corners of the organisation having different roles. What gels this group is the drive to study effects of Gamification and how to implement it in different situations. All of this is done after office hours. We have achieved Engagement!

Looking back, I'm very happy with getting to know and experimenting with Gamification. I will be implementing it in every context where I see a possibility.