What's up with the postman collection

[BrechtSchamp]

Does anyone know what's up with the postman collection. I've installed the new version a while ago and it seems like some things changed... for the worse.

I was confronted with this fact thanks to this topic and the discussion with @Raphael_M :

https://community.meraki.com/t5/Developers-APIs/Clone-existing-network-configuration-while-creating-...

Here's some screenshots:

Old:

New:

• As you can see the new version gives a lot less information. You can deduce a lot from the body in the lower part, but still, why was the top information deleted?
• It seems like the url doesn't use the {{organizationId}} placeholder anymore. It does still seem to work, so this may just be another syntax for the same thing. What gives?
• The copyFromNetworkId parameter isn't mentioned anywhere in the new version. Maybe it was omitted for a reason, maybe not?

@DexterLaBora , is this something you can help out with?

[DexterLaBora · Accepted solution]

The Meraki Postman collection had a major update a few months ago... for the better 😉

It is now based entirely off of the Open API spec, dynamically generated every month with the regular Dashboard API updates. 

Previously, all of the documentation was hand written as markdown into the top description. 

Now,

- all of the parameters are documented in-line. 

- all environment variables are pre-defined in the collection (your personal env. will pass through)

- the authorization header (API key) is automatically applied to all endpoints 

- example responses are included with each endpoint

in-line docs

Collection Settings - Variables and Authorization

Auth headers are applied at runtime

you will see "Temporary Headers" after you hit send.

Examples

[Nash]

@DexterLaBora This is a really good post. Have you considered doing it as a blog? I know we had the Open API launch announcement, but I think a breakdown of current Postman would be great.

@Melissa You should make Dexter do some extra work!

[BrechtSchamp]

You are fast sir! I'm sorry if I may have come across as negative in my post. That was definitely not the intention.

That does seem like a lot of progress. I love the fact that it's built dynamically instead of manually.

I had noticed that the API key had moved to these temporary headers. Basically the collection variables are an alternative to setting up an environment, correct?

How about the documentation for the body though? In the example I gave of the createOrganizationNetworks endpoint, the bulk of the interesting payload is in there rather, than in the params. Questions I have are for example, what name/value pairs can be put in, which ones are obligatory, which ones are optional, what's the syntax of the value? The specific issue we had in the other topic was that the postman collection didn't mention the copyFromNetworkId anywhere.

[DexterLaBora]

@BrechtSchamp , thanks for the feedback.

The collection variables allow us to set a standard convention for the parameter names. We've been working to normalize our global name space, so that instead of "id" we use "organizationId" for example. You can use your personal environment, which will pass any matching variables through to the collection. You may have to update a few variables, but this should rarely change in the future, unless we had to clean up a conflict. 

Regarding the POST body schema... Yeah, I noticed that. Postman doesn't really have a place to to auto-generate the body model. The OAS spec has the information, and our official API Docs show this data as well. I'll look into parsing this info and shoving it in the description.

(FYI: snippet of OAS spec, which shows example and schema data)

[BrechtSchamp]

All right, thanks for the feedback, that makes sense! I'll refer to the official docs for the full information.

[DexterLaBora]

I've already written some extra logic to start including the POST & PUT body models in the descriptions. 
You will see this in the next release (first of every month).

[PhilipDAth]

You can still refer to the "dashboard" API docs.

https://dashboard.meraki.com/api_docs