How to model APIs in HITA?

[stefgou]

Hi,

Until now, we've been using the "old" ARC metamodel to model our APIs, with the concept of IT services and the "service-defined" (for the provider) and "service-used" (for the consumers) relationships.
For example, we had Application A that defines IT services SA1 and SA2. IT service SA2 is an API. And Application B that calls IT service SA2 with the "service-used" relationship.

We would like to switch our model to the "new" HITA metamodel.
Despite carefully reading the documentation, we haven't been able to identify the simplest way to switch our APIs (as IT services) to the HITA metamodel.
What type of object should we use ?
How do we identify the provider and consumers of our APIs ?

[gk]

Thanks for the detailed explanation with screenshots. 

I would like to expand on the original scenarios of modeling API integrations between two applications (App1 and App2). What is the best practice for modeling middleware, e.g., AWS API Gateway, that hosts the Service point (APIs for App1/2 to consume (request point)?

I am using 6.2 and have created middleware as the communication system. I can see the associated flows, but there is no option to link service points.

[AlanB]

If I can add to Patrick's explanation...

From practical experience, I've found with clients that it's not necessary to model every API in detail, and that in the first place it's enough to say "There is an API, and this is what it's called" and create the Service Interface, but not detail every flow, decision, etc. .That's too much work for most contexts.

If you need to know the outcome of an API then associate the appropriate Content as an "outcome" in the Service Definition (Exchange Contract) Outcome, and that can be enough.

The next level of "need to know" is what Content (information/material/finance) is passing each direction as a result of the API. You should now be able to define the simple request/response flows string from the properties of the Service Definition. This avoids about 20 clicks creating the Service Operation, but that can be a little, err, "special" in some recent releases so I normally create a single Servie Operation on a Srervice Definition Diagram and from the Flows tab of its properties define Upstream and Downstream Application Flows and their content. That then aggregates back up to the Structure diagrams on which the Service Definition is drawn.

I hope that helps,

Alan

[PBessodes · Accepted solution]

Hi,
Here is the way we recommend for API description:

[stefgou]

Thanks for the feedback.

I've done some testing with service interfaces and interactions. I must admit, I find it very complex.

If I understand correctly, we have to declare all our APIs as "service interfaces." Why isn't there an entry for service interfaces in the "Inventory" menu? Like there is for "IT services"?

Then, I created "request points" for consumers and "service points" for providers at the "Boundary Components" level of my applications, linking them to my service interface. But I can't seem to view the list of consumers for my service interface. Isn't there a property page or report for that?

[MAngouch]

Hi,

The definition of APIs (catalog of API) are documented using the MetaClass "Service Interface" which describes how/which data are being exchanged. The Metaclass "Service Interaction" is used to identify the provider, consumer and the API used, so the service interaction can be considered are the usage context of the API.

Regards,