Skip to main content
Version: Draft

Diagrams

Effective use case diagrams document the complex behaviour of an API in an easily human readable manner. In this type of diagram, the technical components of the applications and parties involved in the APIs execution are displayed as actors so the reader can focus on the overall flow of the API and interactions between the actors.

When creating use case diagrams, consider the following to ensure the diagram effectively describes the use case/s of the API:

  • Actors - identify the actors involved in the use case, which can include people, systems, businesses
  • Relationships - identify the relationships between the actors in the use cases
  • Purpose - clarify the purpose and role of each actor

Example

The below defines an example use case for the Aotearoa Immunisation Register API. This helps sector developers to understand the overall use case of the API.

ActorsRelationshipsPurpose
John SmithThe Health Sector PatientThe Patient interacts with the health system to receive an annual flu Immunisation
Dr JohnstonJohn Smith's General PractitionerAdministers Immunisations to John, the Patient
HappyHealth PMSThe Practice Management System used by Dr JohnstonSends Immunisation updates to the National register
Aotearoa Immunisation RegisterInterface to access Immunisation recordsThe national Immunisation API

Example Use Case Diagram demonstrating a use case of a patient receiving an Immunisation which is sent to the Immunisation Register

The below is an example of a use case diagram which can be improved using the above tips. The below diagram depicts an "API Consumer" interacting with an API, however, it does not offer information as to the use case it is trying to achieve.

Example Use Case Diagram showing an API Consumer posting an immunisation to Aotearoa Immunisation Register API