How to Use Wireframes to Write RESTful APIs

How to User Wireframes to Write a RESTful API

Howdy, Upstarts!

Wireframes are an excellent tool that can help you to write code cheaply and quickly, but only when they are used properly. In my experience, many software development teams don't use wireframes as efficiently as they could. So in this series of articles, I will take a deep dive into the way that Product Teams and Development Teams use wireframes and explain how to use wireframes to improve software development processes.

In the first article of this series, I outlined a process for the Product Team Handoff that can be used to improve your software development process and help your team write code cheaply and quickly; and in the second article of this series, I went in-depth into the Show and Tell Exercise, which is the first step of this process.

In this article, I will explain the next step of mastering how to use wireframes: Defining an API.

The process that I use for the Product Team Handoff with my software development teams is designed to transform wireframes into a robust specification that my Back End Teams and Front End Teams can use to work in parallel and to minimize the amount of re-work and debugging.

The goal of the Product Team Handoff Process to produce a Technical Specification that enables your development teams to work quickly and with confidence.

The best method to empower your Back End Team and Front End Team to work in parallel is to build a well-defined API Specification. By Defining an API, both your Back End Team and your Front End Team can write their code to this API. As long as each team adheres to this specification, both teams can work at the same time and then integrate their systems very quickly. When done correctly, a good CTO can nearly double the speed of his development teams.

So, the final output of this process should be a clear API Definition that your developers can use to rapidly develop your product.

The second step of the Product Team Handoff Process is the API Definition. To complete this step, you will use the list of Information and Commands that you produced in the previous step, the Show and Tell Exercise; and at the end of this step, your team should have a robust and intuitive API Definition that follows industry best-practices.

What is a RESTful API?

First, let’s make sure we understand what a RESTful API is. An API (Application Programming Interface) is a way to organize the communication between your User and Product; essentially, APIs are a collection of commands to retrieve information for your User and to send information to your Product. A RESTful API is an API that adheres to the RESTful industry-standard syntax. So, an API is a set of commands, and a RESTful API is a set of commands that are written in a specific way. That’s what a RESTful API is.

But how do you write a RESTful API?

Well, the good news is that you have already done the hardest part! Based on your work in the Show and Tell Exercise, you already have a list of commands that your wireframe uses to communicate between your User and your Product. That means that you are, practically, almost done!

So, you already have a list of API commands and the only thing you have left to do is to make sure that your API commands adhere to the proper, RESTful syntax.

So let’s do it!

How do you Write RESTful Commands?

RESTful API Commands have three components: first, they have a URL, which is a web address; second, they have an HTTP Verb, which is the Command that you send to the Product Back End; and third, they have a set of Parameters, which is information that you must send along with the Command.

So the key to this step is to review your list of commands from the Show and Tell exercise and re-write them in a RESTful Syntax. For each of the commands in your list of Show and Tell commands, you must select 1) a URL 2) an HTTP VERB and 3) some information that must accompany your command.

First, you should write the URLs, the web addresses, for your commands. For each command, you should think about the object or resource with which you are interacting, and this resource is used to write the URL. For example, if you are Showing your User information about their User Profile, then your URL should end in a phrase such as user-profile.

Second, you should select HTTP Verbs for your Commands. All of your Show Commands should use a GET Verb. All of your Tell Commands that update existing information in your product should use a PUT Verb. All of your Tell Commands that add new information to your product should be a POST Verb. All of your Tell Commands that remove information from your product should be a DELETE Verb.

Third, you should add the information that must accompany your commands. For GET HTTP Verbs, you should use GET Parameters, and for the other Commands, you should use a JSON Form to send information to your Product.

Simple as that!

One more time, what does this Step Produce at the End?

By the end of this process, you should have a RESTful API Definition. You Back End and Front End Development Teams can now use this to implement code, and because you have defined this API, both teams can work on your new feature at the same time. This means that your Front End Team does not need to wait for your Back End Team to finish before they begin, and you can practically double your Development Velocity.

By implementing this Product Team Handoff Process, a good CTO can help his Engineering Organization deliver software much more cheaply and quickly!

Now You Have a Specification!

In this article, I have explained how to make a list of commands from your Show and Tell Exercise and transform them into a RESTful API Definition. This specification will help your Development Teams to code faster and your Product Teams to have more insight into how Development Teams work.

I use this process to teach my Junior Developers and Product Managers how they can think about products and how to use wireframes. In my experience, this process empowers my teammates to learn much more quickly than providing them a book or a coding course.

Getting good at this process will take a little bit of practice, and I recommend reading up on RESTful API Syntax in some of my other articles.

In my next article, I will provide some best-practices and advice on how to organize your Product and Development Teams around this Product Team Handoff Process.