Designing API products

Traducción en Españól In this post we’ll present our proposal to design an API product global view using  Viewpoint Modelling. The solution we have developed ( and used in real life) integrates ArchiMate and UML modelling languages. In one hand, we describe the business solution of an API Product (Which functionalities will be exposed? What is the value of exposing those functionalities?). In the other hand, we describe the application definition to visualize the dependencies and their orchestration.

Case of study

A zoo needs to design two types of API products:

  1. The first type of an API product must be enterally informative. For example, you could obtain a list of animals with their characteristics, a list of conservation programs, and others.
  2. The second type of API product allows to the zoo enhance the access to its services, such as: selling tickets, geolocation inside the zoo. This product also includes the informative functionality.

We assume the zoo has four internal applications to manage: the animal inventory, the caring specification by animal, the geolocation, the current research programs.


In our proposal we developed four types of viewpoints:

  • ArchiMate Product ViewpointDescribe the business value of a set of functionalities aggregated in one or more products. In this case, we describe the business value of exposing functionalities via API.
  • Archimate Application Cooperation Viewpoint: Describe how two or more applications collaborate each other to execute a functionality. In this case, we use this viewpoint to describe two levels of the API definition. The first level, describe the applications dependency of an API. The second level, describe the API operations and their invoked services from the applications described in the first level.
  • UML Class Diagram: These diagrams allow to describe classes, their attributes, their operations and their relationships. In this proposal, we use to describe an API resource map to obtain the REST operation paths assuring their consistency.
  • UML Sequence Diagram: These diagrams allow to describe all the services invocation in a time line. In this proposal we use this diagram to know how an operation resolve a functionality by describing orderly and in detail the invocated services.


Once we introduced the diagrams, we will describe our solution viewpoint by viewpoint.

ArchiMate Product Viewpoint

Our case of study has two types of products. Each of them, has a reason why is important for the zoo, this is a business value. Then, the product point of view (shown in the following figure) describes in the upper the ArchiMate Values and in the lower the ArchiMate Products

Product View I.png

The main product is called “EAMinds Zoo” and represents the set of functionalities that the zoo needs to offer. The products contained within “EAMinds Zoo” represent features that are distinguished by the type of products the zoo needs. Therefore, both the product “Informational product” and the product “Zoo services product” are associated with the business values ​​described before.

Once we described the products and the values, we need to describe the intrinsic functionalities. In this way, we extend the product model (as shown in the following figure), each product aggregates one or more ArchiMate Business Services that expose the functionalities shown as ArchiMate Business Function in the figure. The business service “Provide caring animal information” exposes a set of functionalities to handle the conservation information and the animals inventory. The business service “Handle zoo services” exposes the functionalities of: geolocation of animals, control of the animal’s inventory, among others. 

Product View II.png

Now the business that wraps the two API products has been described. We now introduce the APIs that resolve the functionalities described in the product model using ArchiMate Application Services. Each application service serves or, is used by, one or more business functions as shown in the figure below.

Product View.png

By this time, we have described the API products and how they are solved with four different APIs: “/conservation_programs”, “/animals”, “/zoo_services” and “/zoo_geolocalation”.

Archimate Application Cooperation Viewpoint (First Level)

In the model below you can find the dependencies of the “/animals” API. As we said before, the API is the interaction of several functionalities, each functionality is the result of interacting with one or several applications (see the following figure). The applications are represented with ArchiMate Application Components, the components that collaborate with each other are aggregated/composed into an ArchiMate Application Collaboration. The collaborations are named with the purpose or grouping the components, in our example we have named the collaboration as: “Generic animal management” and “Specific animal management”. Both collaborations are assigned to an ArchiMate Application Interaction called “Animals API”, this interaction represents all the functionalities exposed by the “/animals” API.

Dependencies View.png

Archimate Application Cooperation Viewpoint (Segundo nivel)

In this model, an additional level of detail is described. This model specifies, all the exposed API operations and their invoked services from the dependency components described in the first level. In the following figure, we describe the “Animals API” aggregates two interactions, each of them represents an operation of the API: “Get animals inventory” and “Get animal status”. In addition, the dependencies section has been expanded. In the upper, we describe the application services used by each interaction of “Animals API”. In the lower, the Data objects associated with the dependency components.

Dependencies View II

UML Class Diagram

In the API definition, you need to define the paths that allows to execute the operations, these paths are made using Resources. The resources are the API functionality concepts. Then, they are not described as actions, they are described as objects, for example: a resource cannot be “ObtainAnimalCaracteristics”, but it could be “Characteristics”. A UML Class Diagram allows you to describe the resources and relationships between resources. Therefore, when you combine them you get the paths of the operations exposed by an API. The concepts that correspond to the resources are described using UML Classes in plural, the combination of the associations between them form the operations paths. There are several proposals for resource maps using RestUML. In this proposal we use the classic UML. 

In the figure below. An interface is used to represent the start of the path, we called the interface “API Animals”. The relationship between the interface and the first resource describes the start of the path called /animals (the name of the API). Next, we assign the path name  to the relationships between resources, for example: the relationship between animals and characteristics is called /charasteristics. The direction of the arrow in the relationships is important to build the paths. Therefore, if we want to obtain the characteristics of an animal, the path is: /animals /characteristics/ (More about API REST).

To specify operations by each element in a resource, the element is represented with a class like the resource. The path between the resource and the element is described with a variable between curly braces, such as /{animal_code}, the selected variable must select a single element of the resource (codes, identifiers, unique keys, etc.) 

Resource Diagram

If you have several ways to call a resource, the relationship between resources must include the name of an attribute, for example: /characteristics/specie_type/{specie_type}. In this context, you can include as many parallel relationships between resources as types you need.

The figure also shows the different types of operations. Each resource contains (GET, PUT, PATH, POST, DELETE) plus an informative description. Only the implemented operations by the API are described.

As an example, we describe some of the paths we obtain with the model:

Path type Path Description
GET:/animals/ GET:/animals/ Get a list of animals.
POST:/animals/{animal_code}/ POST:/animals/{1235}/ Create an animal registry with code 1235.
GET:/animals/{animal_code}/ GET:/animals/{1234}/ Get the animal data with code 1234.
GET:/animals/characteristics/specie_type/{specie_type}/ GET:/animals/characteristics/specie_type/{PantheraLeo}/ Obtain the characteristics of the “Panthera Leo” specie.

UML Sequence Diagram

A sequence diagram is used to describe the sequence of services invocation for each operation of the API. The following figure, describe the life lines and thier correspondence with each components, interfaces in the viewpoins. From the left to right: The interface defined in the resource map, the resource that resolves the operation, a timeline for each component that collaborates in the operation functionality.

The calls between timelines correspond to the services names invoked by each component, and the return contains the output information after the execution of the called service. The output information could be HTTP ###. (More about API REST).

Sequence diagram 1

Integrating other APIs

We described one API and its operation. If we describe the other APIs within the same solution, the services and components will be reused. Then, that a dependency analysis could be executed later.

In the next figure, we show the “/zoo_geolocation” API operations. Later, the “Get animal location” calls the “Get Animal Information” service from “Animal inventory management” component the same we used in “/animals” API. 

animal map

NOTE: In this figure we show a call to a Google® external service for the geolocation functionality.


At this point, a dependencies analysis could be done. We describe the next figure from left to right. The “Animal inventory management” component realizes a “Get animal information” service. The service serves two API / zoo_geolocalization operations and one / animals API operation. Then, each API serves a business functionality, “Handle zoo services” and “Caring animals inventory” respectively. Finally, both functionalities are part of the second product of our case of study called “Zoo services product”.


Like this analysis, many more could be done. If you always follow the pattern properly you can ensure the integrity of the hole design.


In this post, a proposal has been presented to design API products. We describe the design of each APIs operation, a dependency map of the APIs, a description of why and how the APIs are exposed by a product, and the business value of the hole solution. In resume, the functionality from the Business Domain to the Application Domain.

Finally, we apply the concepts using a case of study, so we demonstrate how we have all the elements of a solution traced with each other. As a result, we obtain two APIs products solved with four different APIs, which internally share dependencies.

One Reply to “Designing API products”

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s