OpenAPI / Swagger Principles for APIs and API Products

Not applicable

Hi All,

I have a question about OpenAPI Specification management (I'm going to call it swagger because it is easier to type).

I will use the Petstore example for my discussion as people are familiar with it - http://petstore.swagger.io/#/.

If we think about how the majority of people working on an API Program start out, they will create a set of APIs they want to expose.

In Petstore, we have 3 APIs and a total of 20 resources:

- Pet (8 resources)

- Store (4 resources)

- User (8 resources)

Now I consider Petstore to be an "API Product", and as such, I think it could be reasonable to consider we are only seeing a fraction of the actual resources available for that API.

- Pet (8 resources / 14 resources in total)

- Store (4 resources / 10 resources in total)

- User (8 resources / 20 resources in total)

My questions are these:

1 - Is it reasonable to have a swagger each of my APIs and Resources (internal catalogue) and for my API Products (external catalogue of select APIs and Resources)?

In this case, the internal catalogue would be a swagger for each of my 3 APIs with 14, 10 and 20 resources respectively, and external catalogue as per PetStore - or 1 swagger containing 3 apis and 20 resources.

2 - How would one manage the overhead of this, and the potential myriad of combinations?

3 - How would a client manage the discoverability of this across a company that could have multiple federated teams and business units potentially across the world?

4 - What are some other pain points for large companies with hundreds or thousands of resources to be created, discovered, "productised", versioned and managed?

5 - Do you create a swagger for each of your environments (Dev, Integration Test, User Test, Performacne Test, Production)?

1 0 382
0 REPLIES 0