Showing posts with label YAML. Show all posts
Showing posts with label YAML. Show all posts

Wednesday 18 August 2021

Creating a Power Platform Custom Connector from a Postman Collection

Problem:  I like to discover an API and play with it using Postman.  I save the collection and theoretically I should be able to upload the postman collection into the custom connector to generate the Power Platform connector.  Until a few days ago, the custom connectors only supported Postman v1.0 collections.  And Postman has not save using the v1 format for a long time.  

I was happy to see the Custom connectors support v2.0 and 2.1 of postman collections.  Only problem is while it says it does if is still broken.  So I have to go the old school way.

I wanted to generate custom connectors for HMRC's REST API so that I can connect with the Power Platform.  Option 2 below gives me a way to build my collections using HMRC's API's and generate the appropriate version 2 Swagger definition.

Resolution

Option 1: 

  1. Export the postman collection in v2.1
  2. Upload the postman file to https://apitransform.com/ and generate the OpenAPI specification (version 3.0.0) gets generated.
  3. Upload the OpenAPI 3.0.0 specification file to Transformer | APIMatic and generate the JSON Open API 2.0 version.
  4. In Power Apps add a new custom connector based off the Open API file (version 2.0) to generate the connector.

The process is a pain, but this approach does not need any software installed.  I do feel Power Platform are about to improve by accepting the Postman v2 collections and it would be great if it could read Open API file in YAML and JSON in both V2.0 & 3.0 but any of these permutations would be a game changer.

Warning: Large collections end up with information being lost in the translations.

Option 2: 

  1. Export the postman collection in v2.1
  2. Upload the Postman 2.1 Collection file into Transformer | APIMatic and generate the JSON Open API 2.0 version.
  3. In Power Apps add a new custom connector based off the Open API file (version 2.0) to generate the connector.

Saturday 13 March 2021

APIM OpenAPI Specification Documentation Example within the Developer Portal

Overview:  I find document APIM contracts incredibly important and yet it's often very poorly done.  This post provide a simple YAML and JSON example that can be imported into APIM or any other gateway product for that matter.

The YAML file below can be imported into APIM and published to the developer portal.  The example provides a clear example on options and how an API should be documented.  Developers can see an example of the JSON to use when performing the PUT.  The developers can see more information of a property, for instance a passport number would be a certain length and rather than specifying and option free text string with no description, the developer would know that the property has to come in the correct format.

Simple Open API specification showing a single documented operation for a complex PUT object (YAML).

PB APIM Series:
Documenting you API in the Developer portal (this post)