Postman provides an interactive application for issuing REST APIs calls to a server and reviewing responses.
Basically a REST API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. The call is made using a URL - just like requesting a web page from your browser. In fact, when you request a web page from your browser, the browser is issuing a GET HTTP request for the page.
REST APIs for services such as the open metadata and governance services of Egeria use the full range of HTTP requests as follows:
- GET - retrieving simple structures.
- POST - creating, updating, deleting complex structures and retrieving long lists of information with paging.
- DELETE - deleting simple structures.
With Postman it is possible issue these HTTP requests and experiment with what they do. The Egeria dojos use Postman collections to illustrate the calls and save you typing in the full URLs (which can be quite long :).
Egeria by default uses https:// requests with a self-signed certificate. Any Postman users therefore will need to go into settings->general and turn off 'SSL certificate verification' or requests will fail.
Setting up Postman¶
Postman is a free download with optional enterprise licenses for teams. It includes a wide variety of tutorials to help you go from novice to expert. Familiarity with Postman will help you get the most value from the Egeria tutorials.
Install Postman from the Postman downloads site . At the time of writing 5.9.0 is current and recommended.
Once Postman is installed, start up the application. You should see an initial page something like this:
Setting up Postman with Egeria data¶
We will import two types of information from Egeria's code repository on GitHub: * Environments - these define the values of replaceable variables in the API calls, such as host and server names. * Collections - these define the REST API calls to issue.
Follow through these steps to configure your Postman environment:
Create a new workspace¶
Creating a workspace for egeria helps keep everything we'll work with together. If you mess up your postman files later, you can just create a new environment again to work with
Select the workspace menu at the top of the Postman interface, and create a new one called 'Egeria dojo':
Importing Egeria Postman data¶
We now will * Select 'Import' and select 'GitHub' as the source * Authenticate as required * Select the "main" branch from the odpi/egeria repository on GitHub * Import all the Postman data found
Updating Postman settings¶
Egeria uses secure connections. However the demo environment has self-signed certificates which Postman will not see as valid without further configuration. To simplify this process we will turn off certificate validation in postman:
- Go to settings
- Ensure 'SSL certificate verification' is switched off
Egeria Environment settings¶
The Import process will have imported some egeria environment settings.
In general you can leave the values as default except for hostnames which should be pointed at the relevant Egeria platform. Tutorial content will walk you through this explicitly.
- Make the egeria environment the default in this workspace
Postman is now ready to be used with egeria. Refer back to the tutorials for specific examples, or experiment!
Instructions for contributing new Postman collections are located in the developer-resources .