Don't make me think - API Edition

Don't make me think - API Edition

Years ago i read a book called Don't Make me Think that is useful when designing UIs or Products:

image.png

So i know mostly all developers are very(very...) far away from the UX spectrum but nonetheless we have direct users ! And i'm not talking about the end user that we will use the UI of the product we participate which internally call our beautiful API.

Yes, we have users. Our users are not a different or a mysterious species. Our users are other developers which gladly(or sadly) need to use our APIs. So we have front-end developers that want to parse the resulting, hopefully small, json that our APIs will return as response or other back-end developers that need to use our API to enable a behavior/feature that our team is responsible.

So why make other developers as us suffer ? So what kind of suffering you wonder ?

Let's imagine that you work as a front-end and you need to consume a new API that the glorious backend team has developed last month. So their team lead told you that the API is ready and you give you all what is required to use it. As API keys, Postman collections and a big PDF with documentation. 100 pages with all possible responses for all HTTP Status Codes.

So you say to yourself. Wow this is cool. Everything looks in place. So you start playing with the API and all scenarios look fine. But as usual in software engineering a weird error appears.

Request: POST /magic-api/ Headers: API-KEY : xyz

{
     "name" : "CC",
     "last_name" : "DD",
     "status" : "NEW",
     "start_date" : "02/12/2011"
}

Response: 400 - Bad Request

{
     "error" : "2000-111",
     "message" : "Some fields are no Valid"
}

So you take a break and meditate a little. And after having a clear mind you ask by IM to the backend developers if in their logs what they can see or maybe give you permission to check the logs yourself. The Lead for backend team told you that ask permission to Security Team to access to the logs. So you do and wait all day and you try some random combinations in the request. You check the documentation and found that error code "2000-111" is actually "some fields are not valid". Oh surprise !

Next day you arrive early !. So you check and you got an email from a backend developer:

Subject: Re:Re:Re:Re:Some Fields are not Valid in API call

Status only support 3 values: CREATED, IN_PROGRESS, DONE. ...

And obviously no answer from security with the confirmation of permission to check the logs.

So you try again:

Request: POST /magic-api/ Headers: API-KEY : xyz

{
     "name" : "CC",
     "last_name" : "DD",
     "status" : "CREATED",
     "start_date" : "02/12/2011"
}

Response: 400 - Bad Request

{
     "error" : "2000-112",
     "message" : "Some fields are not correctly Formatted"
}

You always see the glass half full so you check the documentation and found that error code "2000-112" is.....Yep, "some fields are not correctly Formatted".

As you don't have logs available and the backend developers are busy in some random scrum voodoo ritual. You just try several date formats without luck.

Until finally you got access to the logs and you read:

Feb 21 22:00:01 Date cannot be parsed. Expected format is: dd-mm-yyyy

You don't know why they are using that date format. And you will ask UX team later or never.

So finally !! You try again:

Request: POST /magic-api/ Headers: API-KEY : xyz

{
     "name" : "CC",
     "last_name" : "DD",
     "status" : "CREATED",
     "start_date" : "12-02-2011"
}

Response: 200 - OK

{
     "code" : "2000-000",
     "message" : "Success"
}

Success huh ? What "success" means(and not in the philosophical sense) ? The record was created ? is it 'in progress' maybe based on the possible values ? Is it asynchronous ? WTH !

Sad Story :'( right ? But now imagine that you are using an external API. And every question to the creators of the API cost you 0.05 cents or every transaction to test costs you too....or what about you are using an open source library/API !! And maintainers have disappeared in oblivion.

And the solution is just the title of this post:

DON'T MAKE ME THINK !

And im not talking about big documentation !

But for example:

Instead of:

Response: 400 - Bad Request

{
     "error" : "2000-111",
     "message" : "Some fields are no Valid"
}

=>

Response: 400 - Bad Request

{
     "error" : "2000-111",
     "message" : "Status is Invalid use : [CREATED, IN_PROGRESS, DONE]"
}

OR

Instead of:

Response: 400 - Bad Request

{
     "error" : "2000-111",
     "message" : "Some fields are not correctly Formatted"
}

=>

Response: 400 - Bad Request

{
     "error" : "2000-111",
     "message" : "Start_Date format is : [dd-mm-yyyy]"
}

And finally instead of:

Response: 200 - OK

{
     "code" : "2000-000",
     "message" : "Success"
}

=>

{
     "code" : "2000-000",
     "message" : "Record was created. Please check /status endpoint for additional information"
}

Examples are simple in this post. But this simplicity can make our APIs so easy to use and our "users" can focus in new flows/user stories/use cases. Instead of fighting with our api.

:qw


Some good resources:

amazon.com/Dont-Make-Think-Revisited-Usabil..

amazon.com/Irresistible-APIs-Designing-that..