This is an open source template for a toolbox that can be used to deploy API resource centers. This template was originally developed as part of Postman's COVID-19 Resource Center, and then further evolved to be a general template that could be used to deploy a variety of API resources centers. Helping provide single landing pages for a variety of topics, industries, and trends, where developers can find what they need to develop applications.
A Postman API toolbox is a Jekyll powered single page applications that uses an APIs.yaml file as it's core data source. The purpose of an API toolbox is to not just publish a listing of APIs available for developers to use in applicaitons, but also encourage API submissions from the community. Here are the core technologies at play in this Postman API toolbox.
- GitHub - These API toolboxes can be run 100% on GitHub and do not need any outside hosting or APIs to make them work.
- GitHub Pages - The project hosting layer to GitHub, allowing simple project sites to be hosted using a GitHub repository.
- Jekyll - The content in these API toolboxes is managed using a static site content management system called Jekyll.
- APIs.yaml - The data source for these API toolboxes is made available via a YAML file that uses a standard called APIs.yaml, providing a machine readable index of aPIs.
These single page application API toolboxes are designed to run 100% on GitHub, and be updated using Git commits or using the GitHub API. Allowing all APIs to managed via a single APIs.yaml core, and displayed as a single page application using Jekyll, with the hosting environment being GitHub, and GitHub pages. Working to keep the number of folders and files needed to operate each site as minimal as possible, with hosting free.
The site uses a minimal structure to help publish the single page application, keeping the data and the presentation layer as simple and effective as possible. Here is a breakdown of the site outline for operating each API toolbox:
- _data - The central data store for the site.
- apis.yaml - The APIs.yaml file of all APIs.
- _includes - Individual files used to display data.
- api-by-tag-listing.html - Lists all APIs by tag.
- api-listing.html - Lists all of the APIs.
- api-tag-anchors.html - Provides a list of tags as links.
- spec-listing.html - Lists all of the specifications.
- tag-listing.html - Lists all of the tags across aPIs.
- tool-listing.html - Lists all of the open source tools.
- visualization-listing.html - Lists the visualizations for APIs.
- _layouts - The three types of page layouts available.
- default.html - The default layout for each page.
- none-html - When you want to display JSON data.
- post.html - The template that should be used for each blog psot.
- _posts - Where each blog post update for a project goes.
- _config.yml - The configuration file for the Jekyll site.
- apis.json - A generated APIs.json from the APIs.yaml file.
- index.html - The home page for the single page application.
- LICENSE - The license for the project and it's data.
- README.md - The README for the API toolbox project.
You are not required to use all the includes in your index.html for each page, but should provide a diverse range of use cases for displaying relevant API operational data using the APIs.yaml index. Visit the Jekyll site to learn more about the Liquid syntax being used to display the YAML data, or visit the Liquid template language documentation.
Each toolbox uses APIs.yaml as the index for all the APIs included in the toolbox. Using a common standard for describing the toolbox as well as each aPI being included as part of the toolbox. Providing a datastore for the toolbox, but also making the index available in a machine readable way for use in other applications. You can visit APIs.yaml to learn more about the specification, but here are the details you will need to understand this toolbox.
These are the properties that describe the toolbox, providing the name, description, and other details needed to understand what is happening with this API toolbox. Providing the following properties that can be defined when creating a new toolbox, and maintaining over time.
name: Postman COVID-19 API Resource Center
description: During the present novel coronavirus (COVID-19) pandemic, those on the front lines—including health care professionals, researchers, and government experts—need quick, easy access to real-time critical data. This type of information exchange is what APIs do best, and as an API-first company, Postman is committed to providing whatever assistance we can in this area.
image: assets/images/covid-19.png
tags:
- COVID-19
- Coronavirus
created: '2020-08-07'
modified: '2020-08-07'
url: apis.json
specificationVersion: '0.14'
apis:
The Toolbox can contain many different APIs, each defined using the APIs object, providing all of the details needed understand each individual API, and the properties of the APIs, providing human and machine readable details about how to put it to use in applications.
- name: COVID-19 Rich Data Services
description: The COVID-19 Rich Data Services API from MTNA offers curated, high-quality data and metadata from official and popular Coronavirus datasets from around the world. The catalog is updated daily and is constantly growing.
tags:
- Cases
properties:
Each API can have a variety of properties that describe not just the API, but also the operations that support the API, helping provide a variety of properties that can be used as part of the toolbox. Here are some of the properties for the APIs available in each toolbox.
- type: x-postman-documentation
url: https://documenter.getpostman.com/view/2220438/SzYevv9u?version=latest
- type: x-run-in-postman
url: https://app.getpostman.com/run-collection/2220438-d3ac9594-1c67-4176-b103-0c8238ad7aba-SzYevv9u
- type: x-postman-visualizer
x-data:
thumbnail: https://postman-toolboxes2.s3.amazonaws.com/collections/covid-19-rich-data-service/Visualize+COVID-19+cases+over+time+in+the+U.S..png
title: Visualize COVID-19 cases over time in the U.S.
url: https://documenter.getpostman.com/view/2220438/SzYevv9u?version=latest#7310d8a6-43a0-4e44-9313-4639f57e1b38
- type: x-rating
x-data:
rating: 9
- type: x-sources
url: https://covid19.richdataservices.com/rds-explorer/data-product-selection
x-data:
sources:
- name: The COVID Tracking Project
url: https://covidtracking.com/data
Think of the APIs.yaml as the database for the single page application, and the rest of the site files are about rendering that data as the single page application providing an API resources center that can help developers build applications.
The API toolbox leverages GitHub as the underlying host for each toolbox, and leverages GitHub issues for the feedback loop around the project. Allowing the community to submit APIs to be included in the index using GitHub issues, via Git, or using the GitHub API.--providing three distinct ways for getting involved with what is happening with each API toolbox.
- GitHub Issues - GitHub issues are used as the primary way to communicate around each toolbox, allowing anyone to to participate in moving a toolbox forward.
- Git - The APIs.yaml for the toolbox can be updated via commits and pull requests, leveraging Git to add and manage APIs included as part of each API toolbox.
- GitHub API - The APIs.yaml for the toolbox can be updated via the GitHub API, automating the adding and updating of APIs that are included in each API toolbox.
These toolboxes are designed to encourage participation and collaboration from the community, helping add new APIs, rate the quality and value of APIs, and index and publish them so that developers can put to use. Providing documentation, Postman collections, and other resources to onboard with each API being made available.
These API toolboxes are designed to be able to quickly publish API resource centers for a variety of topics, making APIs, specifications, tooling, and other resources available for consumption by developers. Providing a simple, yet robust solution for indexing, evolving, and making APIs available for a variety of uses. Each toolbox is designed for public participation, and encouraging the community to get involved, when it comes to building each resource center, and delivering the most useful APIs possible.
The purpose of these toolboxes is to help make APIs more easily discoverable, while also making each API more usable by developers. Rapidly mapping out the world of APIs, helping break the thousands of available APIs into more meaningful resource centers that reduce friction when understanding what is possible with each APIs. Helping reduce the information overload when it comes finding APIs and putting them to work to provide solutions to common challenges developers, and even non-developers are facing when it comes to integrating systems, and building applications.