Postman API - can't easily distinguish Folders

Ask the Experts and Postman Tips
, ,
1

Hi
I’m writing a app that uses the Postman API directly to generate a Swift SDK to call apis I’ve imported/tested in Postman.

But I’m having problems distinguishing Top Level Items
e.g a Collection.Folder and a Collection.TopLevelRequest in the Collection.Item array.

Example in app I create:
Collection : “Collection1”

  • Top Level Folder : FolderA
    • Nested Request : Request1a
  • Top Level Request : RequestB

The schema mentions Folders are item-group
http://schema.getpostman.com/json/collection/v2.0.0/collection.json
"item": {
“type”: “object”,
“title”: “Item”,
“item-group”: {
“title”: “Folder”,
“item”

But I can never get the api to return an item-group
only items nested in items.

I’m calling
https://api.getpostman.com/collections/8560808a-30d2-424e-5299-ba1cbd229ca8

Is this the right endpoint as response doesn’t need to match scheme collection.json
http://schema.getpostman.com/json/collection/v2.0.0/collection.json

Mixing Folders and Requests in item array mean parsing the json cant be done in one pass.
Can we add “scheme” to Folder and request items

Not following the scheme also means I cant generate the json model classes before running the api.

Also theres an issue with "url"
Sometimes its a String sometimes and Object split into “raw”/“path” etc.
It makes code generation difficult.
Code has to parse the api twice.

Cheers

2

Yes. The URL issue is coming from an incompatibility with an app version where URL’s with description on query param cannot be represented using string as URL. We are thinking of forcing it to output URL as object always. But, I am sure that would offend some existing information.

@kunagpal - did we unify this in 2.1 transformer and Request.toJSON / URL.toJSON

3

It should be always item inside item. The way to distinguish between item and folder (ItemGroup) is that and itemgjoup has a blank item: array inside it.

@kunagpal - can you check with schema bug and the transformer outputs?

4

@clearbrian I’ve tested this out with a sample collection identical to yours, and the response returned by the Postman API is of the following form:

{
  "info": { "name": "Collection1" },
  "item": [
    { "name": "Folder A", "item": [{ "name": "Request1a" }] },
    { "name": "RequestB" }
  ]
}

As for the hybrid nature of URLs, the v2.1.0 collection format will consistently contain URLs as objects. I’d suggest using this version of the collection format for easier processing. The Postman API now returns collections in their v2.1 format by default. This can easily be cross-checked by confirming that the info.schema property in the collection points to the v2.1.0 schema URL: https://schema.getpostman.com/json/collection/v2.1.0/collection.json

@shamasis The result of .toJSON calls will always contain object URLs, for both: Request as well as Url. The transformer also provides object URLs in the v2.0.0 format only if the URL has query parameters or path variables(deprecated), or both.

1 Like
5

yes working now cheers
https://schema.getpostman.com/json/collection/v2.1.0/collection.json

empty folder now has
“item”: [],

URL is always object ?
I added a few sample urls and yes they all seem to return url as object.
the scheme still says its
oneOf object or string
Can I ignore this?

item-folder : still in the scheme
Basically Im asking is the scheme fixed or a suggestion :slight_smile:

Basically the reason I ask is for an app I can point at an api and generate the basic classes in Swift/Java/Kotlin

I’d like to define all the classes first.
The problem with Swagger is the keys aren’t fixed.
The paths of the api calls are in the keys.
Converting json to swift is multi pass operation.
Theres tool where you drop in the json and it generate the model classes for Mappable/Codeable etc

I prefer postman api because I can test in client first.
It imports swagger.
The api is more fixed than swagger. keys are keys/ values are values.
api paths are in the keys!!

And I hopefully generate a swift api for postman in one step.

The reason the scheme.json is important is it shows all the possible keys.
I notice for instance the response in Single collection api may not have anything in it till I call the api.

=====
Future feature request.
A way to make examples as first class api calls.
For instance a lot of apis have a lot of a parameters but only work properly with a combination of them

https://www.mediawiki.org/w/api.php?action=mobileviewprop=
Which information to get depends on the prop param

prop=
text
HTML of selected sections.
sections
Information about all sections on the page.
normalizedtitle
Normalized page title.
lastmodified
ISO 8601 timestamp for when the page was last modified, e.g. “2014-04-13T22:42:14Z”.
lastmodifiedby
Information about the user who modified the page last.
revision
Return the current revision ID of the page.

The swagger would only define it as one api call.
But theres about 6 diff versions of same api call api.php?action=mobileview

in Postman
6 diff request items
same api
differ param values.

6

Yes, the URLs will always be an object in v2.1.0 format collections. Interesting suggestion with the executable responses. It is common to have requests to a single endpoint that can accept several combinations of parameters. We could think along these lines to streamline the user experience.

Once again, thanks for sharing all of this, we really appreciate the context :smile: