How to Write User Stories for Backend APIs

How to Write User Stories for Backend APIs

In this comprehensive guide, we will delve into the art of crafting effective user stories and how to write user stories for backend APIs. As experts in SEO and high-end copywriting, we understand the importance of producing content that not only informs but also outranks competitors on Google. Let’s dive straight into the world of user stories and learn how to master this essential skill.

 

 



Backend API User Story Example 1

Your software called LoanManager handles applications for small business loans for your organization. Your company has recently partnered with a large bank and your application now needs to originate a loan via an API call to the core system  of that large bank – called SuperSoft Core. You are the business analyst on the project and you are asked to write the user story for the API calls that the developer must build.

In this example you must communicate with the backend developer and the solutions architect because they will know the details of the system more than you can. When you meet with them, they explain what needs to happen in the call. Here is an example of how that user story could look:

User Story Title:  Create SuperSoft Core  Loan Origination Connector

User Story

As a applicant I want to be able to have my loan originated to Supersoft Core via an API call when my application is approvedm so that I can be enrolled in business online banking.

Acceptance Criteria

  1. Create a library that implements the HTTP request to these two endpoints
  2. The library must include a interface to allow for dependency injection of the integration implementation
  3. The library must include a mock implementation of the API to allow for testing in the event that the API is not available

In the above example, its ok if you don’t understand it – as long as the developers understand it and this is what they instruct you to write in the body of the user story. Also to note is that in most backend stories you do not need to write the stories in Gherkin format.

 



Backend API User Story Example 2

Let’s continue on the previous example. Now that we have created the connector, we want to use the connector to create an account in theSpupersoft  core system when the loan applications has been approved. This connector must return a loan account number for us to store in Loan Manager system.

User Story Title: Create  Loan Decision Request Service

User Story

As a underwriter, I want to be able to get the loan number when a newloan is created so that I can update the Loan Manager system and complete the final step of underwriting the loan.

Acceptance Criteria

  1. Import the Supersoft Core Loan Origination connector into the Loan Manager application
  2. Create a handler in Loan Manager that uses the Supersoft Core Loan Origination connector
    • Handler must take the application data from the loan application definition
    • Handler must format the data to match the specification of the Supersoft Core Loan Orignation connector
    • Handler must use the lm_id and lm_app_id fields to call the loan origination connector method to originate the loan
    • The handler must check for the response for success status and must save that status in the loan application definition before exiting.

 

Backend API User Story Example 3

In  this example, we need to enable single sign on in order to allow a user to login once and access multiple secure systems. Currently the backend is using person_ID to identify the user and a user story is needed to change from person_ID to use SSN as the identifier.

In this example, all that is needed is the code snippet. Sometimes when writing user stories for backend APIs, its enough to have the developers enter the code snippet so that it can be clear to them what needs to change.

User Story Title: Switch Single Sign On from using Person Id to using SSN

User Story

As a user, I want to be able to use my SSN in order to acces the  Secure Systems Suite so that I can login once and gain access without logging into each system individually.

Acceptance Criteria

This class contains the following code which needs to be updated when we migrate from using person_ID to using SSN:

var socialSecurityNumber = loadSocialSecurityNumberFromToken();
if(isUsCitizenUser(socialSecurityNumber)) {
    PersonNameRecord = findNameRecordBySocialSecurityNumber(
        nameRecords,
        socialSecurityNumber,
        accountType);
} else {
var registrationCode =loadRegistrationCodeFromToken();
    personNameRecord = findNameRecordByRegistrationCode(
        nameRecords,
        registrationCode,
        accountTYpe);
}

repository: sso-intg
class: secSystem

We will use the person_ID from the token instead to get the correct name record regardless of citizenship. To get the person Id use the following code:

public String loadPersonFromToken() {
    return securityContextUtil.getUserToken("person_id, String.class)
        .orElseThrow() -> {
            var message = "'person_id' was not found in the token.";
            log.error(message);
            return new BadRequestException(message);
      });
}

Now remember it doesnt matter if you understand everything that is going on in a backend user story – what matters is if the developers understand it. You must discuss with them and let then lead what goes into the backend user story.

 



Understanding the Importance of User Stories

Before we delve into the specifics, let’s clarify the significance of user stories in the development process. User stories play a crucial role in Agile development methodologies, enabling effective communication between the development team and stakeholders. These stories capture the requirements and expectations of end-users, providing a clear and concise understanding of what needs to be achieved.

The Structure of a User Story

An effective user story should follow a well-defined structure that consists of three key components: the persona, the action, and the goal. When crafting a user story, it is essential to consider the needs and desires of the end-user and express them in a simple and understandable manner.

Persona: Begin the user story by identifying the persona or the role of the user. This helps in contextualizing the story and tailoring it to suit the user’s requirements.

Action: Describe the action that the user wants to perform. This should be concise and highlight the core functionality of the API.

Goal: State the goal or the outcome that the user aims to achieve by performing the specified action. The goal should be clear and measurable.




Creating Comprehensive User Stories

To outrank our competitors in Google, we need to produce highly informative and detailed user stories. Let’s explore the steps to create comprehensive user stories for backend APIs.

Step 1: Conduct In-Depth User Research

In-depth user research is the foundation of crafting effective user stories. Understand your target audience and their pain points to create stories that resonate with them. Engage with stakeholders, conduct surveys, and gather feedback to gain valuable insights.

Step 2: Collaborate with Development Team

Effective user stories are a collaborative effort between product owners, developers, and stakeholders. Involve the development team early in the process to ensure a thorough understanding of the technical requirements and constraints.

Step 3: Use Clear and Concise Language

Avoid technical jargon and use simple, clear language in your user stories. This ensures that all stakeholders can comprehend the stories easily, fostering a shared understanding of the project’s objectives.

Step 4: Employ Acceptance Criteria

Include acceptance criteria for each user story to define the conditions that must be met for the story to be considered complete. This helps in validating the functionality during the testing phase.

Step 5: Prioritize User Stories

Arrange user stories in order of priority to guide the development team in building the most critical functionalities first. Prioritization ensures that the essential features are addressed early in the development process.

Step 6: Incorporate User Feedback

Throughout the development lifecycle, seek continuous feedback from users and stakeholders. This feedback loop helps in refining the user stories and ensures that the API aligns with the users’ needs.

 



Best Practices for Writing User Stories

To outrank our competitors and produce superior content, it is crucial to follow best practices in writing user stories for backend APIs. Here are some essential tips:

Tip 1: Keep User Stories Independent

Each user story should be independent and self-contained. This allows the development team to work on individual stories without dependencies, improving overall efficiency.

Tip 2: Make User Stories Testable

User stories should be written in a way that makes them easily testable. This ensures that the development team can validate the functionality and deliver high-quality results.

Tip 3: Avoid Assumptions

Do not make assumptions about user requirements. Engage with users directly to gather accurate and specific information for crafting user stories.

Tip 4: Review and Refine Regularly

User stories are not set in stone. Review and refine them regularly based on feedback and evolving project needs.

Conclusion

Crafting user stories for backend APIs is an art that requires careful attention to detail and a deep understanding of user needs. By conducting thorough research, collaborating with the development team, and adhering to best practices, we can produce user stories that not only outrank competitors on Google but also serve as invaluable tools in delivering successful API projects.

 

No Comments Yet

Leave a Reply

Your email address will not be published.