Creating Our Sequence Diagrams for an API Design

Learn how to create sequence diagrams as part of the API design process.

We'll cover the following

Sequence Digarams

The second step in the API design method is to create a visual diagram that shows the general sequence of events, otherwise known as a sequence diagram. This is an important part of any good API design. While it doesn’t need to have too many details, such as URLs, HTTP methods, response formats, and so on, it does need to give both the stakeholders and programmers a clear idea of what actions will be available and what data must be passed back and forth when using the API. Essentially, what’s needed is a visual representation of the workflow and internal cycles.

The tool we’d use is an online web application called WebSequenceDiagrams (WSD). The reason is that it’s easy to use, it has some nice features, and has its own API. This last element means we can access the WSD functionality directly from our own command-line applications and utilities. We can use it to build handy tools and even integrate diagramming features into other internal design tools for some of our clients.

Other Diagramming Tools: A handful of diagramming tools are available that are similar to the WSD online application. If this application doesn’t quite work for you or your team, try other drawing applications to find one that fits your needs. Other applications that can be used are PlantUML, Lucidchart, and SequenceDiagram.org. Your team may also already have an approved tool available for you.

For now, we’ll walk through the following steps for diagramming our OnBoarding API:

  1. Create an account at WebSequenceDiagrams.com.
  2. Map out the resource elements of OnboardingAPI workflow.
  3. Describe the transitions of our API.
  4. Include the action parameters for our API transitions.

Creating an account

The first step in our diagramming project is to open our web browser and navigate to http://websequencediagrams.com. This is the application we’ll use to create our diagrams for the Onboarding API project. When we first load the application, it should look similar to the following screenshot:

Get hands-on with 1200+ tech skills courses.