API is user story for developers

If you are part of a large organisation, it is very likely that you work in an agile framework. Things like Epics, and user stories are familiar jargons. According to Atlassian, user stories are short requirements or requests written from the perspective of an end user. User stories are a few sentences in simple language that outline the desired outcome.

We are going to design an API along with low fidelity prototypes for a Driver app. For demonstration purpose I will borrow user stories from the Driver app case study I did a while ago. It is not a prerequisite but I would be happy person if you take the time to read it.

The basic problem statement of the above design task can be converted to the following user story.

As a Driver, I want to finish as many jobs as possible, so that I can earn more money in a day.

We can breakdown the user story to small chunks of activities. The user will follow the following steps:

When offline see trips summary. Go online in order to see jobs. The user identifies a job they want to do. They accept it and start driving to the pickup location. They reach pickup location and confirm the package. They start driving to drop-off and deliver the package. They finish the job. Money is credited to their account.

On top of this happy journey, they have some constraints and additional features.

Users can only accept 1 job at a time. Users can message or call person of interest for a particular job. Users can set radius of their serviceable area. Users can cancel the active job within 5 minutes. If 2 users accept a job at the same time, user nearest to the pickup location will be preferred.

We can easily visualize the above steps into this happy flow.

Let’s analyze each steps and start creating APIs along with rough wireframes. Doing so it will challenge designers to think more in-depth and brainstorm potential edge cases.

1. Offline view (Driver is offline/not accepting jobs)

The basic user story for this requirement can be

As a Driver, I want to see past trips when I am not online, so that I can do strategic planning on how I accept new jobs.

I like to create rough prototypes so that I can visualize my ideas and work my way backwards to identify supporting information or supporting elements.

Which HTTP method?

In this screen, user is not accepting any jobs and they are shown with a job summary and option to go online. Since user is not taking any action at the moment, we will use GET method.

What’s the noun here, what’s the resource?

Also the screen is largely showing all the information related to user, so the noun our resource will be /user/

What should be included in the response body?

All the associated information shown on the screen will be included in the response body. So this will include summary data, user’s profile photo and current location. This representation will be shown as a JSON list.

If we visualize the api and wireframe side-by-side it may look something like this.

2. Online View (Driver is online/view jobs)

As a Driver, I want to view available jobs when I am online, so that I can take up new jobs.

Which HTTP method?

In this screen, user is now online and can view available jobs. We will use GET method.

What’s the noun here, what’s the resource?

This screen will use 2 resources. One will be /user/ described above to show the online status at the bottom and user’s current location, and a new resource which we will create i.e. /jobs/

What should be included in the response body?

All the information related to jobs available. Then the data can be prioritized to showcase on the cards. This representation will be shown as a JSON list.

API:

If you notice the response body, I included currency format, and unit of measurement. This makes the API scalable and our mindset automatically starts working on ways we can make the format as general as possible so that it is scalable.

3. Accept a job

As a Driver, I want to accept the job, so that I can earn associated incentive.

Which HTTP method?

In this screen, user is taking action by accepting a job. We will use POST method.

What’s the noun here, what’s the resource?

Since we already have /jobs/ as URL and we are taking action on that resource, so accepting the jobs can easily be represented as the POSTing of /jobs/ resource. This is explained much more better in this article.

What should be included in the request body?

Since we are taking an action now, the request body should include driver’s current location which can be part of live status conveyed to consumers.

Designing multiple states

Writing APIs when wireframing also enables designers to look out for edge cases and different states of a software.

3a. Successfully accept job

Knowing Status codes easily completes half of our job. There are mainly 5 types of HTTP Status Codes we can design for

1xx Informational 2xx Success 3xx Redirection 4xx Client Error 5xx Server Error

This list helps me a great deal while designing screens for multiple contexts.

If you want to know more about them, check out this documentation.

Getting back to our user story, the POST /jobs/ operations will create a new active job. For successful creations we use 201 Created status code.

3b. Handling errors