I work as a Business Analyst in a S/W development firm. At a previous company I was a BA in Asset Management, and the BAs there were more Business oriented (i.e. less technically inclined).

We are currently building a web application and I'm using JIRA to write the user stories, acceptance criteria etc for the functional requirements.

I'm writing user stories to describe functional requirements:

For example:

As a Client User, I want a confirmation email to be sent once I've registered an account, So that I have confirmation that my registration has been completed.

Acceptance Criteria:

  • The registration wizard will send an email to the registered email ID once the wizard has registered the Client User
  • A confirmation message will be displayed on screen so that the Client User knows that registration has completed
  • Client User will automatically be redirected to the Portal upon clicking on 'Finish' etc.

There are some developers that think I need to write the associated API tickets as well, and there are other developers that think it's not the role of the BA.

The thing is that whilst I've studied IT, I've never actually studied APIs in detail nor have I previously worked as a professional developer. I moved into Business Analysis directly.

Is it the role of a BA to write API tickets in a software development project? Or is it the role of the developer to write the associated API tickets as subtasks of the stories I write?

All the BA sites I've visited only talk about functional/non-functional requirements when writing User Stories (like the example I provided), and not of writing API tickets.


  • 1
    No, even this is far too proscriptive for my tastes.
    – Telastyn
    Mar 4, 2018 at 3:09
  • proscriptive?? So are you a BA in an Agile team? You don't write API Stories? Who Does? Mar 4, 2018 at 3:46
  • 1
    What kind of API do you have in mind in your question? Internal program's API? Or some kind of web API for allowing external programs to access your system by some REST service? "API" is a very general term, please clarify what you are talking about.
    – Doc Brown
    Mar 4, 2018 at 8:18
  • 1
    Are you delivering the APIs to your customers, so they can write a front-end against it, or are they just an internal detail of how the delivered website works? Mar 4, 2018 at 11:09
  • 3
    No, I am a team lead. And nobody working with my teams include UI implementation for business requirements. API details are even worse. Acceptance criteria should describe what must be achieved, not how.
    – Telastyn
    Mar 4, 2018 at 13:33

6 Answers 6


IMHO the key point, which was already mentioned in the comments, is if the API is an external requirement (because your system offers third parties a possibility to access it programmatically), or if it is an internal implementation detail.

For the former situation, it can be sensible to see the API as part of the business requirements, so something which a BA would be responsible for. For the latter, it makes often more sense to let the API be in the responsibility of the developers in the team.

Note this is just a "model by the book": if you want that separation between the "typical dev role" and "the typical BA role" in your organization to be that strict is up to you and your team. A really agile team should distribute the responsibilities the way which works best among them, not the way some theoretic model defines them.


tl;dr; You shouldn't write API user stories (in your context), but not all backlog items are user stories.

In the comments, you say that the API is part of your architecture. It is not, itself, a product that the user consumes (as opposed to products like AWS which have an API that users leverage to manage their services). Therefor, it is impossible to write a user story (from the user's point of view) for the API. Keep in mind that originally user stories were actually written by users.

Moreover, the API in this case is how I, as a developer, would deliver on another user story, not the what is being delivered. To use your example, the what is an email confirmation, and making a call to the API is how the team implements that capability, so that cleanly falls into the task category.

Of course, user stories are not required for Scrum. "Add confirmation email call to REST API" can be a backlog item - it just isn't a User Story. There are many reasons why I would recommend using user stories instead of backlog items like this, but if you find yourself in a situation where you need one, it is not inherently anti-scrum to have one (you may be infringing on the dev team's autonomy around implementation, but that's another topic).

Finally, anyone can write items in the backlog. Scrum just says that the product owner is accountable to the prioritization and health of the backlog. If the team sees the need for another user story or other type of backlog item, they are allowed to write it.


First thing first....if you are a BA that is business inclined, then you are a Business Process Analyst. If you are a BA that is technically inclined (and most times you would come from a development background), then you are a Business Systems Analyst. It's high time the industry made a clear distinction between these two types of Business Analysts.

Based on your description above, if you were never a developer nor understand how systems communicate via APIs, then you are a Business Process Analyst. The role you are occupying requires someone who used to be a developer and I say this because I currently work as Business Systems Analyst and my background is in C#.net web development.

If you are expected to work as a Business Analyst on a software development project (Business Systems Analyst), clearly it's your responsibility to define the API specification, for the product you are developing and some of the details expected of you would be the headers, query parameters to be parsed, the logical datatypes, the field lengths etc.

The API specification is not necessarily the 'How' of the system (hence I disagree with what Daniel said in his comment), it is in fact part of the 'What' of the system in that it describes 'what' information to send to the email program and the logical datatype (not the physical datatype).

You need to tell the developer what information to send across to the email program. If I was the developer on your project, I would ask you the same question. A simple analogy would be if you ask me to build you a vehicle. You would have to tell me what you would use the vehicle for, how many passengers to carry, would it be used for heavy duty or not etc....based on your answer to these questions, I would be able to determine whether to build you a car, a motorbike, a truck, a tractor, or a 4x4. Therefore, for the email, I would also be interested in knowing how many recipients, would there be any CC or BCC, should the email be mobile optimsed?, should it be plain text or HTML, are there any encryption or anonymisation needs when sending the email etc .......An example of the 'How' for this story is which protocol to use to send the email i.e. SMTP and this is down to the developer.....I hope this helps.

Ps: In the scenario described, since the API specification is to define what information to be exchanged between the two systems, I would write this as part of my success criteria for the user story not as a separate story, but that is me.The most important thing is the information is documented.

I also don't understand why everyone is asking if your API is to be consumed internally or externally.....I think your user story says it all....you are building a registration form as part of a web application and you require the web app to interface with an email program (possibly your organisations email program). Guys, the answer is in the user story!!!


I believe that anyone can write API requirements as long as they are familiar with the domain, APIs, API testing and have some common sense. But, I have seen some Business Analysts & Product Managers writing API stories without basic & essential details, thereby making the stories useless to developers and testers. Hence, developers and testers have to figure out the requirements themselves.

For example, I have seen API stories that don't mention the headers, query parameters, sample responses etc. Some APIs have fields like date, percentage etc., but the expected formats for these fields are missing. (US or UK date format ?, Percentage with 1 or 2 decimal places ? Does a BA or PM really need a fancy degree to ask simple questions like these ?). In all stories, the response for different happy path or normal use case scenarios is never mentioned.

As doc brown rightly mentioned, writing requirements can be the entire team's responsibility and not just BA or PM. But, if your BA or PM are not skilled and smart enough to do it, then developers and QA should take up that responsibility.


No. An API is an interface between two (or more) pieces of software (e.g. client side and server side code). As such I think it's generally best for the nature of the API to be negotiated between the developers, or teams, responsible for building and maintaining those two pieces of software.


I don't think there is a clear answer to this. It depends on what your team needs and your solution. Let me explain:

Generally speaking in agile our goal is to provide end user value. There is a risk with API or other tech stories to create something that is of no value, or at least out of context. Imagine a story as in "I want API xzy to retrieve the address field". That may be technically correct, but why are we doing it? In fact, you may even be proscribing implementation which is questionable.

So what we should do is write stories that are end-user facing.

Having said this, I have written API stories in a number of cases: - if your API is public facing, then you have a user, be the human or system with a vested interest not only in the functional but also non functional part of the API (for instance 'minimal number of calls'). In that case it may very well be justified to write API stories. - also, and maybe more controversial, if you imaging a system with a number of services that all use an internal configuration service as part of their service delivery, you may have teams that own individual services. In this case it may make sense to write API stories to communicate between teams. Having said this, there is a risk that you may work in silos and my question would be: why is one team not doing the full end to end?

A great book (independent of whether you are working with microservices or not) that addresses this is Sam Newman's book Building Microservices where he discusses various patterns around this: https://samnewman.io/talks/principles-of-microservices/

Also, the Agile Podcast The Burn Up will have an episode about exactly this in May :)

Not the answer you're looking for? Browse other questions tagged or ask your own question.