Showing posts with label OpenAPI. Show all posts
Showing posts with label OpenAPI. Show all posts

Sunday 15 January 2023

Postman to verify OpenAPI's are running

Problem:  Our teams rely on a 3rd party API for a new project being delivered, the API's are in a state of change and are constantly up and down making life tough for the teams replying on the API.

Hypothesis:  I need a quick way to check the API's to see if they are all working in dev, and test.  I have two postman collections for the REST API's.  If i combine them and check the key API's using postman I can save myself and other time as I'll know the current state of the API's.

Solution: Create a site collection that does the API verification, you can make it more complex with data and variables.

Problem:  I can open Postman and run the test which takes a few minutes.  We need to do this quicker.

Hypothesis: I'd like to be able to run the tests quickly on demand.  Use postman CLI and Powershell to run the collection and display the result.

Solution

1) Add the Postman CLI to my machine:

PS> powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"

2) In postman generate an API Key for the Collection > Run Collection > Automate runs via CLI > Generate the API Key > Copy the generated code


3) Run the code in PS to verify it works correctly.

4) Copy the PS code into a newly Created ps1 file on your local machine, I added a read line so I can see the result.


5) Run the API.ps1 file and verify the result

6) Setup a desktop short-cut to run and see the result.  Right click the API.ps1 file and create a shortcut on your desktop.  Right click and amend the target and amend the target value:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -ExecutionPolicy Bypass -File C:\Users\PaulBeck\Downloads\Projects\PoC\Postman\API.ps1

7) Save and run the shortcut to verify.

Problem:  Monitor and alert DTAP API's are working and performance

Resolution: I want to monitor that my endpoints specified in my Postman collection in Dev, UAT et al. are working, can be more than 1 endpoint using Postman Monitor.

Next steps: Add to automated DevOps processes, using Newman.

Saturday 17 September 2022

Generating a Canvas App from a Custom Connector (Open API)

Overview: The Power Platform CLI in August was updated and 1 of the new features is the ability to use the CLI command line to generate a Canvas app using an Open API as the data source.

The Power CLI supports the GET and POST endpoints.  Which is normally +85% of the endpoints anyway.  

In this post I walk thru the steps to add books using an Open API and retrieve all the books as well as the new book added.  

Solution

1. I used the free postman API endpoints (2 gets and a post) > Exported the collection

2. In Power Apps > using a Solution > Add a new Custom Connector (tip: I used Automate)> Upload from a Postman Collection > Pass in the Postman collection generated in the last step.   Save the Custom Connection as shown below.  Lastly test the Custom Connector.
3. I used Visual Studio code with the Power Platform Extension
Using the Power Platform CLI, in the terminal run ps> pac to verify the Power Platform extension is available.

// Get the environment you want to work on
ps> pac admin list

// Get the Custom Connector Name or Id you are going to base the Canvas app on
ps> pac connector list --environment a9adbbba-c45d-eac1

// Generate the msapp package
ps> pac canvas create --msapp "C:\Radimaging\BookDemo.msapp" --connector-display-name "BookDemoCN" --environment "a9adbbba-c45d"


4. Import the export Power App.  Select your environment, and create a new Canvas driven Power App.  "Open" has recently changed in the UI.


The app will get created, I had to add the Custom Connector to the App and you are ready to customise

Beware: Custom Connectors and Connection References in Managed Solutions.  It's a good idea to check they work in the deployment pipelines as the rework can be a pain.  

Summary: This is a great way to build an application quickly using the pac create.  It is a bit rough, and needs amending after import on the 3 endpoints I've used but a great start to a new feature. 

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)


Wednesday 24 June 2020

Postman API Builder Intro

Overview: Tools for building and mocking API's.  Swagger has good tooling and my original preferred choice.  APIM - Great tooling, part of Azure and easy to replace mocks as you go along with the live implementation.  Postman is offering a great set of functionality to rival Swagger and APIM.  This post looks at Postman's new functionality around building API's.

Postman API Builder:
Not only a test rig, it now offers the ability to build API's and mock:
  • Mock - so you can test supports key and OAuth authentication
  • Assert Tests - You can specify asserts in postman
  • Test suite - generate collections/Collection Runner - Allows a set of related tests to run sequentially.
]
  • Document the API
  • Monitor
  • Version control for changes e.g. GITHub
  • API Versions supported
  • Note: Free plan has all of this, limited on the number of API's but all the features are on the free plan.  The main notation formats are support including:  Open API specification (OAS) & GraphQL
Summary:
I like Swagger tooling, I have done a few projects find APIM fantastic for building API's quickly.  Postman historically was merely my test rig but looking at the functionality, Postman API Builder is a great option for designing and building API's.  Postman is a good tool for building into CI/CD pipelines to validate API's.

Few more assert examples:

Postman offers a service to monitor API's using your postman collections, these can be triggered using Curl so can build into DevOps, Power Automated scheduled flows,....
sentry.io looks good as an alternative option

Sunday 12 January 2020

API Management Mocking

Problem:  Create an Open API Specification (OAS) endpoint for testing using APIM

Background:
  • Azure has a great service to bring multiple API's under a single publishable layer (think MuleSoft).  I like to use APIM to setup an initial contract that developers can use before setting up the actual API.  This allows both the consumer teams and the back-end development team to work independently to this OpenAPI agreed contract. 
  • Swagger originally owned and ended up creating the OpenAPI specification (OAS) that now of companies now use.
  • Swagger has great tooling for creating OAS API's, documentation, stub hosting and generating code such as .NET core that you can import into your dev environment. 
  • Azure has a developer APIM instance licence that is relatively inexpensive (creating an APIM instance takes up to 20 minutes) but leaving it running for my personal dev is pretty expensive.
Overview:  This post outlines the steps to setup an APIM instance using an OpenAPI file created in swagger.  The APIM service shall be setup to return mock data.

Steps:
1. Create a new instance of APIM - Do this first as it takes up to 20 minutes before the service is ready.
1. Create an APIM instance
2. Open swagger.io in a browser and signup, "Create New", this gives you your starting OAS file for your custom API.

2. Login to Swagger and create the Open API file using YAML
3. Using the Swagger Editor, create the desired endpoints.  It took me a few hours to get use to YAML as it is space sensitive but very readable.
3. Swagger editor
4. On the top right of the Swagger editor is the "Export" option.  Click Export > Download API > JSON Unresolved.  And keep the .json file ready to import into your APIM service.
5. Open APIM, and add a new API.  APIs > Add API > Open API as show below.
Import OAS file into APIM
 6. Import the file and the fields get populated per you instructions.
Upload the OpenAPI json file into APIM
7. The list of operations shows up - in my case i only have a single GET operation call \Get Customers
APIM Service is now created but not connected to a back-end

8. Add Mocking to the end point.  Highlight the Operation i.e. \Get List all Customers > Inbound Processing (Add Policy) button.  Select "Mock-responses" > Save


9. Generate the JSON responses:
a) Select the Operation i.e. \GET List all customers
b) Frontend drop down > Form-based editor
c) Click the "Responses" tab
d) Click the "200 OK" link
e) Click in the Sample Box, and "Auto Generate", Save


 The APIM service is now setup and we are ready to test.

1. Test using APIM's Testing tool


Check the 200 Response
Mocked response from APIM test tool

2. Testing using Postman
Open Postman, and craft the request as shown below:
Postman APIM testing

NoteThere are several competitor products like Mulesoft, Amazon API gateway, Postman and Swagger also offer a lot of these features.  There are other products that I have not used such as Kong API Gateway, GCP has Apigee, Gartner has a list of competitors and the magic quadrant done each year.

Summary:  It is pretty straight forward to setup APIM mocking as shown above.  And then easy to test it using Azure APIM tests and Postman.   This post show how to add various mocked APIM responses.   

Sunday 10 November 2019

OpenAPI Tooling working with WebAPI and APIM Notes

Editor.swagger.io is a great tool for building OAS files.  The Swagger editor is easy to use and has a preview for changes.

VS Code is a great IDE for working with OpenAPI  specification 2.0 and 3.0 files (also know and Swagger specification).  These 3 extensions are a good idea for working with a OpenAPI specification file.


Spotlight also has an editor which is nice.  Takes a little bit of getting use to, but make complex API design first easier.

Sunday 12 May 2019

Designing an API with Web API on Azure

.NET core is great for creating a Web API project to provide an API.
Tip: Swagger is a great tool that has an editor to specify your API.  With the OpenAPI specification for your API, you can generate documentation, or use the code generation feature to generate tests or C# code.
Tip:  Use the Swashbuckle.AspNetCore Nugget package to generate an OpenAPI specification for your API if you use a code first approach.

Do not trust incoming parameters, you must validate.  Always respond with generic header error messages so you don't give away back-end information.  Ensure you log all errors and review them.

Preferred High Level Design I like for Web API projects

The API needs to return Status Codes to allow consumers/clients to know how there operations are doing so I design with these standard HTTP status codes:

CodeCode Status Meaning
200OK (GET)
201Created (POST or PUT)
202Accepted.  Used for long running operations.
204Resource has been deleted (DELETE)
304Not Modified
400Bad Request
401Not Authorized
403Forbidden
404Not Found
422Entity Validation Issue
429Too many Requests (Implement at APIM layer only)
500Internal Error
    



  • The bold codes are the three minimum set of response codes I will use for a simple API.  The next 4 most important are italicized.
  • Name resources/EndPoints with nouns and I always use lowercase e.g. /api/customers is better than verb noun which was common a few years ago, e.g., /api/GetAllCustomers  NB!  No verbs in URL naming.
  • Keep the URL's simple.
  • Always use HTTPS.
  • DateTime data is always in UTC.
  • Sensitive information must be in the header or body, not in the URL as it is not encrypted.

URL/Resource

GET

(read)

POST

(create)

PUT

(Update)

DELETE

(Delete)

/customers

List all customers

Add/created a new customer

Bulk update customers

Bulk Delete or Generally error and don’t implement

/customers/35

Get a specific customer.  Customer 35 is John DoeNAUpdate the John Doe recordDelete the John Doe object/record

HTTP Methods to Support
GETReturn the current value of an object
PUTReplace or update an object
DELETEDelete an object
POSTCreate a new object.  Return 201 for created and 202 for long running operations.
* PATCH - is also used for updating objects but normally a subsets of existing data

Versioning
API's need to change but there can be multiple client applications consuming my OpenAPI.  We use versioning to ensure I don't break existing implementations.  There are different strategies for versioning API's:
  • No versioning:   https://pbeck.co.uk/customers/35
  • URI versioning: https://pbeck.co.uk/v2/customers/35
  • Query string versioning: https://pbeck/customers/35?version=2
  • Header Versioning:  Not in the URL but passed in the header (my preferred option)
APIM has a great implementation for versioning.  Generally, adding optional data is pretty safe for API versioning.  You need to give 3rd parties using your API's time to implement the new version before deprecating and versions.

Tip: Enforce versions are present in the header.  No version return bad request.

JSON
JSON property names SHOULD be camelCased.

Query Params
Allow filtering using query param e.g. https://pbeck.co.uk/customers?firstname='paul'
Allow sorting for the most common properties
DateTime should be in UTC - The pattern for this date and time format is YYYY-MM-DDThh:mm:ss.sTZD. It is recommended to use the ISO-8601 format.  UI does adjustment for local time display.

Paging
Requests must have max return limit e.g. 100 items.  Specifying the limit param if you want to change the size of the dataset to return.

CORS
Cross Origin Request will need to be supported, reply on OAuth for who can use the API.

HATEOAS 
Good way to navigate around your API.  And a principle worth adhering to where possible.  

Authentication and Authorization
API's access should be via OAuth2.0.  It is very easy to hook APIM and underlying App Service (Web API) up to AAD B2C.  Scopes are used for authorization.

Code Review/Quality
"Linting is the automated checking of your source code for programmatic and stylistic errors. This is done by using a lint tool (otherwise known as linter)".   Examples of Linting Tools are Resharper, StyleCopSonarQube, ...

Security

It's a good idea to also have a WAF in front of your API.