API Connect

To develop an API in APIC, the common steps often include using an existing json or yaml file which has the API (swagger 2 or openapi 3) spec.

Some of the fancier APIs are not defined by a single json or yaml file, but have a structure like this:

To develop, host, and/or publish the "directory" API you also need to include all the referenced schema items in the "types.json" file.

Many APIs are made this way, so that you can have dozens of small APIs that all refer to the same single schema document. This is efficient, smart, reduces repetition (and reduces the data footprint), minimizes moving parts (and reduces risk), and helps with consistency and version control.

This is perfectly lovely, but does the APIC developer portal support it? Can I import and validate and publish a file collection like this and APIC will bundle them properly?

ReadyAPI and Postman supports it just fine. So long as the files are in the same directory, ReadyAPI and Postman find the types.json (or referenced schema) file by name when it reads the API definition, and includes that file as part of the overall combined schema.

I tried the same thing in APIC, and this feature seems to be missing... it only accepts the one file, and then throw errors on the references because it can't look inside other files (automatically or manually). Maybe there's a command line option? Not sure.

Do I have to bundle these files (combining the referenced schema and the API definition into one file) myself using third party tools?

What third party bundling tools does IBM recommend?

Thanks,

------------------------------
Thomas Dalsin
------------------------------

Hiya,

The use of common files like that can be useful at API development time but it is not so useful for consumers once the API is in production. From a governance point of view the API document forms the contract and is what is versioned, if critical parts of that contract are in external unversioned files then youre going to suffer from a governance point of view.

As such a common solution is to inline the external references when the APIs are imported into API Connect, and the API Designer will do that for you (I'm not sure the online API Manager UI can).

Then there is a single API contract which can be versioned, governed and published out to the portal for consumers.

Hope that helps,

Chris