• Nnenna

Basics of API (2)

Say you are asked to support a Dev Team by writing a technical specification that describes how to interact with an Address API . The first step would be to agree on which open-source API (service) that's the best to use. For the sake of this explanation, let's assume that the Dev team have agreed to use getaddress.io

The BA will be expected to create a document that would detail the triggers of the API (what I mean is, the Devs might want to know what data would be sent to the API and what response would be expected). At the top of your head, you would expect that an address API would need a postcode as a trigger (Request) and an address, or list of addresses that correspond with that postcode will be received (Response). If you do not know this, ASK the Devs or the Tech Lead. Click here to read more about how to specify an API or click here if you would like a refresher on the Basics of API.

Now. Let's take a breather. Take a step back. And think of the below analogy:

When thinking about APIs, picture the old mobile phones with a speed dial functionality. The speed dial is that cool feature that saved users from dialling 11 digits to make one call. The speed dial allowed users to push just ONE button, which, in turn, would call the person/number associated with the button. I believe this was done for greater UX and and time-efficiency. Now. This. Is. The Concept. Of APIs.

Now let's go back to the address API. To create a great User experience (UX), rather than expect a user to type in their...

  • First line of Address

  • Second line of Address

  • Third Line of Address

  • Postcode

  • County

  • Country

...an API exists in the universe, which when called/dialled, would populate the above address fields with an address that is associated with a trigger. For addresses, the trigger is mostly a postcode. This means that the REQUEST was a Postcode, and the RESPONSE was an Address (if only one address associated with that postcode) OR a list of addresses (if multiple addresses are associated with that postcode).

So, Nnenna, how do I document an API:

You can’t, shouldn’t and don’t document APIs. This has nothing to do with Business analysis in anyway and would only concern you if you are a Systems Analyst. Documenting an API is like documenting source codes. It’s absurd for a BA to document a source code because it is documented as it is created in its IDE (Visual Studios, Unity, etc). An example of an interface for documenting an API is Swagger, or notepad.

Ok, Nnenna, what do I do as a BA:

To be honest, I don't think it is right to ask a BA to work on anything concerning APIs (Technical BA or not, unless the BA is paid a combined salary of a BA and SA/Dev). But, all things equal, the BA could want to be technically savvy to identify when an API may be needed to improve user experience or to shorten user journeys. If that is the case, I would expect the BA to ask:

"Hi Devs, does an API exist to eliminate needless typing by the users?"

"Hi Devs, is an API needed to get real-time data from the headquarters to the local offices?".

If they say, "Yes!", your next question would be, "So what information would you need from me to achieve this?"


Nnenna, what if I want to capture the services in swagger and put them in my FRS/User Stories:

Why?-- While you are at that, make coffee for the Devs, fan them and offer foot massages, since you have lots of free time.

Unless the aim of capturing/snipping the services in swagger is to document the current state of the services, all you’ll end up doing is creating duplicates, which is an anti-behaviour for a BA. Those snips will never be updated when the API is updated, which means that that the services were snipped for no reason and could misdirect the future BA/SA. Also, some APIs are paid services from Third-Parties, meaning that you may be in breach if you store their APIs somewhere else, if they withdraw their contract with your organisation. Truthfully, having their services saved in a document somewhere doesn't mean it can be used, but some providers may not like you having their property.

But Nnenna, I was told to create an API:

No you weren’t. You were told to elicit the requirements that the Devs would need to read or create API. You working on an API is the same as you writing code, and only Devs code. What a Dev would need to create an API is an understanding of the problem the service aims to solve and the data that the service should receive; including any business rules it should process, as well as the data it should send back.

What do you mean by Read an API

Let's go back to the speed dial analogy. If you own the mobile phone, you would create a speed dial to your taste, where 1= mum's number , 2 = dad's number, 3 = darling's number, 4 = daycare, etc.

Because you created the above speed dial, you know what to press to contact the above people. However, if someone else picked up your phone, how they know what to press? You may need someone to write this out and paste on the phone. But.

In truth, the Devs would be able to easily read the API documentation from the providers, without needing you to ask the providers to explain what the services are. Now that I type this, I can see that the BA isn't actually needed in reading an API documentation, unless the Devs don't understand the service. If this happens, you can resolve it by scheduling a meeting for the two parties to communicate, while you file your nails. (P.S: actually, the meeting should be scheduled by the Project/Delivery Manager, as staff capabilities is a PM/DM's work description).

The only other time that the BA could be needed is if the executives what to know what services (APIs) the Dev team spend business money on (sometimes it costs money to user a service/API). Then that analogy in this font colour, could play out. To successfully execute this analogy, the BA will sit with the Devs, ask them to list out the services and explain what they are for, while documenting the responses. The BA would document things like:

  • a notification service to get notifications every 5s

  • a license service to retrieve a car's metadata

  • a colour service to retrieve all the colours in the world, etc.

What do you mean by Create an API

Just as a reminder, an API is a resource that Devs use to make their lives easy (rather than dial 11 digits, push 1 button and call). However, the ripple effect of making their lives easy, could make the life of the end-user easy as well. So the creation part of an API, is probably where you need a BA because users may be involved.

The Devs may ask you to detail the kind a data that you would like to be returned, when you push a button or when you load a new page. This means that they may create a notification service but you would guide them that the notification service must return details about the notification, the date, the read/unread status, the sender of the notification. Another example of where a BA comes in is in the use of Business Rules. The Dev might want to know any business rule that must be applied in the background (server) before the data is displayed on the user interface. An example is creating a business rule that checks the age of the user, before displaying a PG13 movie.


Firstly, the lingo is not security but authentication. This is solely handled by the Devs unless a particular type of security (Auth) is expressly requested for by the owner of the app (client), of which you just pass the message across to the Dev.

Say, you own a database that contained a list of cheap restaurants in Manchester. Anyone that wants to access this database must include an authentication in their Request, which if correct, will trigger a Response from you (the response could even be you Requesting for a password from them (this is security). The point is, an outsider must pass the Auth, for you to even respond to them.

See "Authentication" as you telling your boyfriend to horn three times, when he arrives, so you would know he is outside; whether or not you go outside, is left to you; whether or not you lock your door, is also up to you.

Rest and Soap?

Soap is phasing out. Rest is the new "it".

I'm afraid to ask you to leave your questions, comments or contrary opinions :D. The link to the Technical Specification will not work, because I will publish it in a week's time-- Stay tuned!

#fairygodmother #businessAnalysis #API #services #questions


Recent Posts

See All