If you’re reading this article, it’s probably because you’ve undertaken a software design project, so first of all, congratulations! Developing a software product is an enormous challenge, but it’s also enormously rewarding. And considering you’ve landed on this article, you’re off to a good start. This is your ultimate design thinking resource for developing your API.
We’ll cover everything you need to know to make your API outstanding, including:
- What is an API, anyway?
- What is design thinking, and why does it matter?
- Tools of the trade
API stands for Application Programming Interface.
For any reasonably complex software product, it’s unavoidable-- at some point, your program is going to need to communicate with another computer for some reason. When we’re talking about internet-enabled products, that usually means a server and a client. But how do you actually facilitate this communication? That’s where your API comes in.
An API, or Application Programming Interface, is the part of a program that allows other programs to talk to it. It might help to think of it as a UI, but instead of designing it to allow people to interface with your application, you’re designing it for other computers to interface with your application. However, just like UI for people, your API needs to be well-designed.
Applying design thinking to API design helps everyone.
At this point, you might be wondering why API design matters. After all, it’s intended for computers, right? That should make it easy. You should be able to slap something together quickly and have it up and running without too much thought.
Well, it’s not quite that simple. Even though your API allows for communication between computers, people are still involved in the programming. If humans can’t understand your API design, the client-server interaction is going to be messy, inefficient, and time-consuming.
You’re a good person, and you certainly don’t want to throw anyone’s workflow for a loop with poor API design. That’s where design thinking comes in.
Design Thinking and API-First Design
Before you can jump into design thinking, you first have to gather your thinkers. But who should you include in your API design design sessions?
If you’ve followed ProgrammableWeb for a while, you might be familiar with API-first design, a design methodology that emphasizes working collaboratively with key stakeholders to design, mockup, implement, and document the API from the very beginning of the process.
The big idea behind API-first design is beginning the design process as if the existing IT estate doesn’t place any constraints on your API. First, focus on creating an awesome API that meets all of yours and your stakeholders’ needs. The IT estate can be twisted into submission later.
As you work through the design thinking principles outlined below:
- Make sure to get your designs in front of stakeholders early and often
- Don’t be afraid to put the constraints of the IT estate on the backburner as you really hone in on an awesome design
Design thinking is all about improving usability.
Design thinking, like many design processes, looks very different depending on who you ask. Many prolific designers rely on 10 principles of good design to make sure their work is accessible to their audience, and 6 of those 10 principles can be applied to ensure your API is an amazing interface for people and computers alike:
- Make it useful
- Make it understandable
- Be thorough
- Be simple
- Build it to last
If it seems pretty straightforward, that’s because it is! Applying design thinking isn’t necessarily difficult, it just requires a little bit of extra mental legwork at the beginning to ensure things run smoothly later on.
No, we’re not talking about color schemes here. When it comes to APIs, aesthetics is a pretty easy concept to master. Basically, you just want to keep things nice and tidy. Spell check your API endpoints. Implement one, single naming convention that is used throughout the API-- don’t switch it up! Use conventional spelling, words, and phrases. There are many opportunities to get creative with web development, but this isn’t one of them.
Useful + Understandable
These design thinking principles go hand in hand. People shouldn’t need to be experts on your product in order to use or understand your API-- your API should be a tool that’s accessible to anyone. You may not be an expert on the Slack queuing system-- heck, you may not know if they’re using a Relational Database or NoSQL-- but even without that in-depth understanding, you can still formulate a request to the Slack APITrack this API without too much trouble.
Thorough + Simple
Again, these design principles work very closely with one another, although it might not be obvious at first glance. When designing your API, you want to think through every last detail, but you also have to be careful not to over engineer your solutions. Be thorough, but don’t over complicate matters.
Imagine this: You’ve coded your database, and it’s awesome. So are your service layer and your API. And now it’s time to move on to your client codebase. Piece of cake, right? But shortly into creating your client codebase, you stumble upon a problem. Maybe you didn’t think something through to the very end, and now you’re going to have to go back and make some major changes on the backend. Yikes.
Don’t let this happen to you. Your API will grow and evolve a lot as you’re building it, but after it’s done, it should be done. In order to ensure your API works as it’s supposed to, we highly recommend tackling the client code first.
Essential Tools for API Design
When you think of the tools you need for designing an API, your mind probably jumps to technical tools. For example, if you take our advice and write client code first, there are plenty of tools out there that let you set up a mock server based on OAI (formerly knowns as Swagger) documentation.
However, if you really want to approach building an API from a design thinking perspective, you’re going to need other tools as well.
Collaborating in the Cloud for API Design
Before you jump into coding your API, you’ll want to spend some time developing ideas with your team. “Pen before pixel,” as they say-- although that advice might be slightly misleading. There are major benefits to storing your team’s early sketches and ideation in the cloud, including:
- Improved collaboration
- Easy file recovery and version history
- Syncing across devices
Things to Think About
What sorts of things should your team think about before the actual coding gets underway? Creating an API can be complex, and there are plenty of things you should map out early on.
Here’s our checklist of key points to cover:
- Model structure
- URL scheme
- Process flow
It’s okay for this to be messy! That’s part of the charm of design thinking. In the beginning, every idea is worth considering, and by getting all of the ideas you can come up with out on the table, you have the largest pool of ideas from which to draw up your plan.
What emerges from this collaboration and discussion will be the blueprint for your API design.
Applying design thinking to API design might sound like a lot of work, and to be perfectly honest, it is. However, these tools and principles will eliminate countless headaches down the road. You can thank us later.
This is a sponsored post for Dropbox. All opinions are my own. Dropbox is not affiliated with nor endorses any other products or services mentioned.