How do I write user stories for system internal requirements?

Question

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.

Edit:

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?

Answer 1

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.

Answer 2

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.

Answer 3

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.