A day in the life of an API-developer: On-boarding issue

We are thrilled to have you and like your first day to be educational and fun, so you will learn about our API-first development workflow by having fun with Lego, Postman and OpenAI (DALL-E, GPT-3) 🏢 ➡️ 🤖 ➡️ 🍫 🚗 🖼️

Tours overview

We will touch many aspects of both the producer as well as consumer lifecycle for API-first development.

There are three tours available:

API Consumer Tour - Short one, covers how to
- [x] discover via search / private API network
- [ ] Optional discover via published documentation
- [x] evaluate / fork
- [ ] Optional Explore workspace types and their visibility (comparison to GitHub here)
- [ ] integrate (client) already published APIs as an end user
- [ ] Optional suggest changes to the API (documentation) - pull requests - shortest producer cycle
- [ ] Optional Use tests and collection variables to chain multiple APIs together
- [ ] Optional Use comments on request level to suggest adding a new material - longer producer cycle
- [ ] Optional Use collection comment to suggest adding our own company/new material - longest producer cycle
API Producer Tour - Collaboration Aspects Documentation - Shortest one
- [ ] get notified about new pull requests
- [ ] review pull requests, ask for follow up changes
- [ ] merge pull requests
- [ ] Optional see updated online docs
API Producer Tour - Design Aspect - Longest One, covers how to
- [ ] Optional find out what changes have been requested
- [ ] define and design a new API functionality
- [ ] develop it in a separate branch
- [ ] add OpenAPI responses using helper collections
- [ ] Optional discover OpenAI workspaces from Postman Public API network search
- [ ] integrate with CI/CD
- [ ] Optional collaborate with coworkers
- [ ] add test cases using data files
- [ ] Optional run Postman test collections from UI with data files and special environments
- [ ] generate collections out of OpenAPI definitions
- [ ] add Mock server responses
- [ ] Optional discover GitHub workspaces from Postman Public API network categories
- [ ] Optional test security and governance rules
- [ ] Publish/deploy new API version
- [ ] Optional observe governance and security checks with a monitor
- [ ] Optional Publish/distribute public developer documentation with special DocuMock environment
API Producer Tour - Implementation Aspects - Medium one, covers how to
- [ ] discover what changes needs to be done
- [ ] Optional fork integration tests to workspace
- [ ] evaluate / environments
- [ ] figure out what changed between versions
- [ ] integrate with ci/cd and work in isolation
- [ ] code generation (external/internal)
- [ ] Optional discover GitHub workspaces from Postman Public API network categories
- [ ] run tests manually
- [ ] Postman and CI/CD environments (Heroku)
- [ ] faker library and data files
- [ ] monitor staging and production
- [ ] publish docu

The API Consumer Tour - Fun with AI and lego

[ ] There are multiple ways how you can discover our A(i)ppealing companies API. The easiest way would be to just search for "AI lego" in the Postman search bar and restrict your search to our private API network

You can also manually navigate to the (AI Examples folders) in our private API network.

The highlighted entry is the Public A(i)ppealing Companies Workspace. Inside the workspace, you will find the collection that is backing the public facing documentation. This collection was automatically generated by the OpenAPI definition of its corresponding internal workspace.

[ ] This is how our A(i)ppealing Companies API will look in our public developer portal and how our end users can evaluate its functionalities without leaving their browser, just click on the "Run in Postman" button to fork and evaluate the API

Fork to your personal namespace

[ ] Navigate to the List all companies request, hit the send button and then click on the navigate tab to get an overview of the curated companies and their products

[ ] Now, we like to actually get some pictures generated by AI, switch to the Get company request and select one of the curated companies and material as parameter, hit send and visualize

[ ] Optional To integrate the API in your own apps, open the code tab on the right, and switch to your favourite programming language. You can also change the environment on the upper right to DocuStaging and hit send again to see how the generated code snippets change:

[ ] Optional If you like to suggest some changes on the API, feel free to suggest the change you like to see and create a pull request (your workspace needs to be public for this to work)

[ ] Optional If you like to understand which OpenAI APIs can be used to implement the A(i)ppealing companies API, have a look at the OpenAI POC (fun with lego) collection. Its OpenAI Experiments folder shows the used API calls whereas the API MashUp folder chains multiple requests of the different APIs together by using collection variables and test scripts.

[ ] Optional Now, let's try what happens when we try out a completely new material like platin, go to the A(i)ppealing companies 1.2.x Playground and try out what happens if we set the material to platin.

As you can see, platin is not yet supported, so let's ask the API producers to introduce that material in a request comment

[ ] Optional While we are it, we can also ask for our own company and product to be included as default example and in the list of curated companies, this time, we use the ability to comment on the parameter level and on the connection level

The API Producer Tour - Very short - Collaboration Aspect Docs

[ ] Once your API consumer created the pull request with the suggested material change, you will get a new notification

Click on View Pull Request to review the change

[ ] If we like the change, we can approve, and merge it right away, in this case, we like to have a change and use the commenting functionality to ask for that change

[ ] The API consumer would receive a notification with our comment

Based on the comment, a new change can be suggested by modifying the collection again

[ ] Once satisfied with the change it can get approved and merged

[ ] Optional Check the online docs, they have been updated automatically

The API Producer Tour - Design Aspects

[ ] Optional Check your notifications to learn about the API design (and implementation) change that is asked for

Tell the requestor that you are on it and resolve the comment

[ ] Optional You are asked to design a new feature for the A(i)ppealing Companies API, you will discover the related company internal workspace that is part of our private API network (AI Examples folders), just search for "AI lego"

[ ] Our goal is to design a curated product example for our own company and introduce a new material to create visually appealing representations, to test our API definition related changes in isolation, we will create a new branch called after our company

[ ] Optional We do not need to manually create the example record for our company, instead we can use the OpenAI POC (fun with lego) with its built-in visualizations, tests and collection variables to make use of the OpenAI API to create the records and mocks semi-automatically.

[ ] Optional You may wonder how we learned about the functionalities of the OpenAI API with its text and image generation facilities. We actually found the API and its collection in Postman's Public API network by searching for term OpenAI. We could have also browsed Postman's Artificial Intelligence Category to find the API. Any public workspace / API could be published to the world wide community, maybe one step in the future when our API is ready for prime time 😊

[ ] Replace the first response example with the one for your company, change the example for the companyId to our id, add the new material to the allowed enum values for the material parameter and set it as example value, push the changes upstream and create a PR

[ ] You will recognize, that the test cases will still fail as the Mock Server for the API conformance does not know anything about our company yet, let's examine the log

[ ] Optional You can run the same test suite from Postman when you run the Governance Checks collection with the CuratedMocks environment and the data/companies.csv data file.

[ ] To fix the problem, we will need to create a Mock response for our company in the CuratedMockResponses collection. There are multiple ways to do this, but one easy way would be to create a new collection from our OpenAPI definition, copy it to the workspace, and finally copy the generated OK example response of the Get Company request to the Get company request of the Mock collection. Please rename the response to OK (your company) for better readability.

[ ] To also list your company in the list of curated company responses, replace the content of the Mock collections's OK response of the List all companies response with your generated one.

[ ] You will see your PR updated with your generated product picture:

[ ] Optional If you wonder how the results of the tests appeared in your PR, have a look at the Update GitHub PR / Issue request. It is using previously set collection variables in combination with pre-request and test scripts.

The request itself has been copied from our version of the GitHub Web API Reference which has been forked from the public workspace in Postman's Public API Network DevOps category.

[ ] Optional The governance tests also include API governance and security checks, try to trigger a breaking test by adding a trailing slash to an endpoint or have a look at realtime rule validation by changing the API version number to something non-semver

[ ] Fix any kind of temporary compliance and security errors you have introduced and bump the version number of the API (increase the patch version), commit and push your changes.
[ ] Publish your API design with a release note

[ ] Optional Fork the Governance Checks collection of your newly created API version to the workspace, rename them to add the API version number and create a monitor that is running them daily with with the MonitorCuratedMocks environment and the data/companies.csv data file.

[ ] Optional Publish the documentation from the generated collection you copied to your workspace together with the DocuMock Environment

So far, we can test your API with our mock data, no new pictures will actually be generated and the "ai" mode does not work either - for this we need a real backend implementation of our new API which brings us to the internal consumer flow.

The API Producer Flow - Implementation Aspects

[ ] Optional To implement the new version of our API, you will discover the related company internal workspace who is part of our private API network (AI Examples folders). Select the latest version of the API, scroll down to the release logs to see what has changed.

[ ] Optional If you like to find out the differences between the previously implemented API in detail, have a look at the API object itself , and check the Git branch associated with the versions you like to compare:

You can use GitHub's branch comparison feature for the details:

[ ] In our particular case, the associated API test suites did not change significantly (only ids), so there is no need to fork the API version specific test suites into our workspace again, if there was a bigger change, we would need to fork at least the Governance Checks collection of the versioned API and adjust our CI/CD config. In our case, we just inspect the runs of the matching Integration Tests collection.

[ ] Optional If we manually run the the suite with our updated data/companies.csv against the CuratedMocks collection, we should see all tests pass as this is the same setup as for the API-first producer lifecycle. However, if we switch the environment to staging, which is used for CI/CD and run it manually again, we will get a validation error as the new material is not yet recognized by the backend.

[ ] Inside the PR of the API changes, we see a new Heroku preview environment that is used to run our integration test suite against the reference implementation in the same branch.

As we have not changed the backend (other than the new test case) yet, we will see similar validation errors in CI/CD as we did when running the integration test suite manually in Postman.

- [ ] To change the backend code, you could either use the internal server code generator

or an external generator like OpenAPI Tools

Review the changes proposed, commit and push them to your branch

[ ] After the backend code has been adjusted to accept the new material you introduced, the iteration for your newly introduced company will fail for a different reason - there is no curated data for your company in the backend yet.

To solve this issue, copy the OK example response from the CuratedMockResponses collection to data/companies.json in your branch, commit and push.

After that, test cases should successfully run through 🎉

[ ] Optional If you wonder how the results of the tests appeared in your PR, have a look at the Update GitHub PR / Issue request. It is using previously set collection variables in combination with pre-request and test scripts.

The request itself has been copied from our version of the GitHub Web API Reference which has been forked from the public workspace in Postman's Public API Network DevOps category.

[ ] Optional If you ran the integration suite manually against the staging environment, it would still fail at this point as we have not yet promoted the preview build in our branch to staging:

We could adjust the preview environment's baseUrl to point to the Heroku preview env if we wanted to simulate what CI/CD does in our branch with the review app.

[ ] We can now merge the pull request to promote the preview build to staging.

[ ] Optional Make a copy of the integration test suite and change the company with a random name using the faker library, run it multiple iterations against staging

[ ] Optional If we are satisfied with the tests and behaviour in the staging environment, we can promote the staging build to production in Heroku and trigger a manual workflow for prod tests.

[ ] Optional Update the Published Docs collection with your newly introduced material and see how the connected public facing documentation automatically updates as well.

[ ] Optional Have a look at the setup monitors and their environments, add a new monitor that runs tests for random companies every day from three different companies

Advanced Features probably for another day 😅

[ ] Live collections
[ ] API contract generator
[ ] API fuzzing / naughty strings
[ ] Deployment to API gateways
[ ] Integration with APM
[ ] Integration Overview
[ ] Capturing network requests
[ ] GraphQL, AsyncAPI, Open API 3.1 Webhooks, gRPC
[ ] Flows
[ ] Access rights / administration
[ ] Custom spectral rules for security and compliance
[ ] Externalized test libraries
[ ] Advanced response visualization
[ ] Visual Studio Code Integration
[ ] Partner Workspaces
[ ] Custom token scanning
[ ] Accessing Postman via API for further integration (custom dev portal publishing, server/client code generation)
[ ] Find out more about environments and partial variable overrides in CI/CD
[ ] Checking workspace best practices for InnerSource and OpenSource

postman-solutions-eng / aippealing-companies-template

Onboarding Issue #28