How to create OAS which represent runtime API product?

An API product is a selection of operations in one or many API proxies.

In the runtime environment, resource path filters are used to limit/scope which operations should be a part of the API product.

We need to figure out a way to create an OAS (swagger) file which describes all the available operations in an API products after resource path filters has been applied.

The resulting OAS file will later be used in the dev portal to restrict access to content (OAS is this context == API product).

It´s really important that we get a 1-to-1 mapping between whats available in runtime and documented in the dev portal.

From what I´ve read, Apigee2OpenAPI can probably be used set the base for the OAS generation, but how to restrict it even further based on resource path filters?

Kind regards, Erik

Solved Solved
1 4 550
1 ACCEPTED SOLUTION

gsjurseth
Participant I

Hi @Erik Andersson,

Yep, I get it. No, there is not way to do this today, but I think it's an interesting approach. As for a request for enhancement, it's best if that comes from a customer. If you want to propose this on behalf of your customer that would be great.

In the meantime I think you're going to have to build something that munges a proxy resources with the api-product path specifications to generate specs. Probably not too difficult, but definitely a customization.

Thanks,

/geir

View solution in original post

4 REPLIES 4

gsjurseth
Participant I

Hi @Erik Andersson

First I want to just clarify that though limiting scope to certain resources is enforced inside the api-proxy you certainly *can* utilize allowed scopes inside of products as well. In this way much of this controlling mechanism moves from the proxy and into the product. That is, you can set allowed scopes *and* set only those paths you want to allow for a given proxy and limit what's allowed for a given set of credentials. I wanted to bring this up because it may itself be another way to drive what I'm going to describe below.

Now, regarding the second half and publishing different types of documentation in the dev portal for different types of user access. For me this breaks down into several questions:

1) Can you generate documentation from proxies or products by clicking a button in the product or making an api call?

No. You can, however, pretty easily use the proxy definition to generate a spec. I don't love this idea in generic sense because we don't always expose all paths and resources inside of api-proxies that are actually served by the backend. Having said that, if you're sure that all relevant paths and resources are listed there then it will work. It's really just a matter of parsing that primary proxy xml file in the api proxy.

You could do the same for the products, and the way I'd see this is that the product would recursively call the first script and from there generate the docs....

2) Can you publish different products that are associated with particular roles.

Yes, and there is more information here:

https://docs.apigee.com/api-platform/publish/drupal/managing-role-based-access-content-your-develope...

3) Can this all be combined into a workflow?

Yes. You could absolutely combine all of this into a single workflow so that whatever deployed and updated your proxies, also updated the product, generated the various specs (including the different kinds of specs for different roles), and then used APIs to auto-publish all of this Drupal.

4) Do you like this idea?

I'm wary of this... I think this approach is fine so long as your api-proxies are the canonical representation of all resources you're serving through Apigee. If that's the case then so be it, but it's not the kind of thing we'd want to make any kind of default because so often we really do act as a proxy and are ignorant of all the real resource contraints.

Make sense?

Thanks,

/geir

First I want to just clarify that though limiting scope to certain resources is enforced inside the api-proxy you certainly *can* utilize allowed scopes inside of products as well. In this way much of this controlling mechanism moves from the proxy and into the product. That is, you can set allowed scopes *and* set only those paths you want to allow for a given proxy and limit what's allowed for a given set of credentials.

I think we´re talking about the same thing. This is how I phrased it:

In the run-time environment, resource path filters are used to limit/scope which operations should be a part of the API product.

Here´s an example to make sure we´re on the same page. Let´s assume that we want to cherry pick operations from 10 different API proxies. To do that we use resource path filters. If we would generate an Open API def from the complete 10 API proxies, we would create API reference docs that contain too much information since the user is in practice only allowed to access a subset of all 10 API proxies.

You really don´t want to manually craft the OpenAPI def based on how you think the actual API products looks after all restrictions (implemented by resource path filers) since it is very likely to go wrong.

Unless the community can provide something useful I definitely think we need to build something ourselves. But of course it would be preferable if Apigee could provide this type of functionality out of the box. <- Hint Hint, feature request ... 🙂

Moving on, you wrote:

"Now, regarding the second half and publishing different types of documentation in the dev portal for different types of user access. For me this breaks down into several questions:"

Thanks, but we´ve already got this covered. We´ll be using a taxonomy based content access control module + an Apigee module for limiting returned API products during developer onboarding based on roles.

Kind regards, Erik

gsjurseth
Participant I

Hi @Erik Andersson,

Yep, I get it. No, there is not way to do this today, but I think it's an interesting approach. As for a request for enhancement, it's best if that comes from a customer. If you want to propose this on behalf of your customer that would be great.

In the meantime I think you're going to have to build something that munges a proxy resources with the api-product path specifications to generate specs. Probably not too difficult, but definitely a customization.

Thanks,

/geir

Adding to this thread in case others are interested and find this useful... this kind of OpenAPI document manipulation/projection is the purpose of an open source project called Spec Math that Google sponsored two years ago.