Visualising Complex APIs Using API Map
medium.com
Visualising Complex APIs Using API Map
1–9 of 9 posts
Re: Visualising Complex APIs Using API Map
#2How does it explain what the request and response formats / fields are?
Re: Visualising Complex APIs Using API Map
#3How does it explain what the request and response formats / fields are?
By the sounds of it, you'd use this as an overview and use something like Swagger for the actual details of each endpoint.
(For that matter, if you output the diagram in a format that supports hyperlinks like SVG or PDF, you could link from the diagram directly into Swagger.)
Re: Visualising Complex APIs Using API Map
#4This is a neat idea; it's sort of an entity-relationship diagram or class diagram for API resources.
In fact, if your audience is familiar with these sorts of diagrams, I wonder if it'd be more readily scannable if you denoted the cardinality of the relationships with the sort of notation you'd see in ERDs or CDs? (Personally, I'm a big fan of Crow's Foot.)
Re: Visualising Complex APIs Using API Map
#5Looks like an erd from databases.
I think I didn't see one since like ten years?
Re: Visualising Complex APIs Using API Map
#6How does it explain what the request and response formats / fields are?
By the sounds of it, you'd use this as an overview and use something like Swagger for the actual details of each endpoint. (For that matter, if you output the diagram in a format that supports hyperlinks like SVG or PDF, you could link from the diagram directly into Swagger.)
That's exactly the point of this diagram - make audience familiar with the API's domain before throwing them into useful detail of specs like Swagger.
You brought another very good point about being able to hyperlink directly into Swagger, something we have been talking about a lot recently. Unfortunately, we have not come across a tool that does this satisfactorily.
Re: Visualising Complex APIs Using API Map
#7Looks like an erd from databases. I think I didn't see one since like ten years?
It has lot of similarities with ERD so can say it is ERD for API.
Re: Visualising Complex APIs Using API Map
#8How does it explain what the request and response formats / fields are?
That is intentionally left out of this diagram for two reasons
(1) - That detail is covered by API specs like Swagger (2) - Two endpoints that return the same resource (of the back of two different operations on the same resource) may return a slightly different format/field. This is up to the developer of the API and best captured in API spces.
Re: Visualising Complex APIs Using API Map
#9How does it explain what the request and response formats / fields are?
That is intentionally left out of this diagram for two reasons (1) - That detail is covered by API specs like Swagger (2) - Two endpoints that return the same resource (of the back of two different operations on the same resource) may return a slightly different format/field. This is up to the developer of the API and best captured in API spces.
Thank you for the answer.