Some requirements of a system are for the system itself, or for the developers, how do I write user stories for this?

For example, there are requirements for a system to:

  1. provide APIs so that partner apps can interactive with it, and
  2. the APIs should be flexible and rich enough for various apps.

I can write user story for the first one as below:

As an Partner, I want to call the APIs provided by the system so that I can build additional functionality on it.

But for the second one, I don't know how to write. It seems like more benefit to developers so that they don't need to develop a new API for a new partner.


Sorry that the example I provided is not good user stories. They are too broad or vague as many pointed out. But please pay attention to my point that how to write stories for an system internal requirement.

Two opinions I see so far from answers:

  1. Non user facing one need not a user story. User story is about a user.
  2. Non-functional requirements or system constraints can be captured as user story. The user is relevant stakeholder like system developers.

What do you think?

  • 2
    Regarding, "But for the second one, I don't know how to write. It seems like more benefit to developers so that they don't need to develop a new API for a new partner.", the YAGNI (you ain't going to need it) principle potentially applies here. It's often easier to write a new API for a new partner, rather than making a small set of APIs so complex and configurable, they theoretically meet future needs.
    – David Arno
    Dec 3, 2019 at 11:27
  • What you are calling a "story" is really an epic of epics. It is WAY too broad for a story. You need to refine this and work with your clients to tease out the specific behavior they want from these APIs. Dec 3, 2019 at 18:11
  • By API do you mean web services or micro services architecture? Or an actual code library API? Dec 3, 2019 at 22:34
  • @GregBurghardt API here is web service RESTful APIs. But as I updated the question earlier, the example doesn't matter. What I wanted to know is the general solution.
    – Wei Huang
    Dec 4, 2019 at 4:35

3 Answers 3


Your examples are vague non-functional requirements related to interoperability:

  1. vaguely states that interoperability has to be provided, and how (API);
  2. vaguely states how good this interoperability should be.

But that’s real life: at the beginning of a project people rarely know precisely what they need, and it’s our job to help them on this matter.

There’s some controversy about taking or not non-functional requirements in the backlog as user story.

Mike Cohn, who is THE reference on user stories, defends this approach and explains that such requirements create constrains on the possible design and should be taken into consideration. He recommends that “user” would then no longer be the end-user, but the relevant stakeholder. You identified them: the partner for 1), and the partner’s developers for 2).

Of course your requirements are only vague wishes for the time being: you can’t make anything with them! It’s as if a user would state: “As an employee, I would like a GUI so that I can use the software easily”.

In practice, this means that the story is not ready yet. Fortunately, we’re agile and this will not block us from grooming it in the backlog:

a user story is only a placeholder for a conversation

So put your initial story in the backlog as a placeholder, and hold these conversation as soon as possible, to get a clearer picture of what is really needed, with a level of accuracy sufficient to develop the API and to test it.

  • I like your answer. A user story is a placeholder for conversation. It can't be clear enough from the very beginning. The blog you gave kind of address my question, but non-functional requirements like eliability, availability, portability,... are also what user can see and feel. In my case, seems only relevant to system developers. Or maybe I could say "As a new partner, I want the prepared set of APIs to be rich and flexible to cover my development need so that I don't need to wait long for system developers to develop a special version for me."?
    – Wei Huang
    Dec 3, 2019 at 22:05

In your particular example, you don't have good requirements nor a good user story. Simply saying "provide an API for partner apps" or "make the APIs flexible and rich enough" aren't good requirements, from a traditional or agile perspective.

My suggestion would be to not write user stories for things that aren't user facing. The user story format is not the only way to capture needs, wants, and expectations for a system. There are different ways to split and decompose user stories, but a user story should be about a user. One approach may be to split the user story into smaller tasks, but deliver the whole user story. Another approach may be to identify buildable, testable, deliverable, and deployable units of work, even if they aren't visible to the user and treat these as enablement work.

You should be to identify who the actor(s) are. In this case, the thing that interacts with your APIs is an external system. I would start by capturing the things that you want external systems (your partner apps) to be able to do - the things that you want them to be able to query or read, update, delete, and create. You can express these as user stories, if you choose to, but alternative formats can also be considered.

Once you know what things you want to expose behind an API, you can start to refine and decompose. Maybe some of the exposed things are long running tasks that can't be completed in real time and you'll need to build queuing and processing workers. Maybe you need to handle authentication and authorization. Some of these may be discretely buildable and testable and should be work that you define and capture while others are done as part of exposing a new API endpoint.


I think the main problem here is that you are not treating third party developers as users of your system.

Sometimes your users are not end users. Sometimes they are developers. Once you redefine your "user" to be a third party developer, you can really start breaking down the behavior into smaller and more manageable chunks.

Sure the behavior might follow what your main user-facing application needs, but those are separate user stories focused on the end user, whose prerequisites are the APIs being developed.

Lastly, and most importantly, don't build more than you have an immediate need for. There is nothing wrong with building something that can be extended, but don't extend it until you have a customer need requiring that extension. Keep your API stories tightly focused, and avoid general stories like you mentioned in your question.

  • I do treat 3rd party developers (I call them Partner) in my question. What makes me uncertain is whether to treat ourselves who will develop the system (I call them developers) as users. Thank you for your advice of avoid over engineering.
    – Wei Huang
    Dec 5, 2019 at 4:12
  • @WeiHuang: treat yourselves as just another partner. Dec 5, 2019 at 13:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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