-
Notifications
You must be signed in to change notification settings - Fork 5
API Responses
The content of this page can be discussed at https://github.com/postman-open-technologies/knowledge-base/discussions/40
The knowledge API responses can be organized as follows:
- statistical queries: aggregated counts and percentages based on various dimensions and filters parameters
- resource queries: returning raw data on collected resources, such as JSON files (or a subset of), attachments (validation/spectral reports)
The structure and content of the responses will vary depending on the category or the query itself. But in general, responses coming out of the API should contain both data and metadata and be based on a template like:
{
"metadata": {...}
"data": [...] or {...}
}
The response content should as much as possible be aligned with standards and best practices (rather than create something from scratch). Specifications to take under consideration include:
- Data on the Web Best Practices
- Model for Tabular Data and Metadata on the Web
- CSV on the web
- Data Catalog Vocabulary (DCAT)
- Data Documentation Initiative (DDI)
- Statistical Data and Metadata Exchange Standard (SDMX)
- schema.org Dataset and related resources
Date/time-related property values must be based on the ISO-8601 standard.
The Knowledge Base API needs to return bot data and metadata in answers to queries producing statistics used for generating reports or answering research questions.
The metadata section of the response should document the initial query, describe the data structure, and contain additional helpful information (such as execution statistics, timestamps, descriptive statistics, and the like).
At this point in time, the data is primarily rectangular in nature, so the data section is expected to be a collection of records. These can be used to produce tables in various ways.
Besides our proprietary response, W3C CSV on the web could be used as an available output. Providing output formats compatible with popular rendering platforms such as Plotly, Google Charts, and AMCharts might also be beneficial for rapid visualizations. Download options should also be available.
An example of such an approach can be seen in MTNA's Rich Data Services platform. See the developer's documentation for further information. Here is a sample tabulation query and the underlying API response.
The metadata section of the response can contain the following elements:
- Identification: uniquely identifying this query / call
- The original query: describes the query and input parameters
- Query statistics: query execution time and any other useful statistics
- Data dictionary: describes the structure oofr the data and the variables, including data type, name/description, dimension/measure. We could use JSON
- Descriptive statistics: number of records, page (for paginated queries)
The data section holds the output of the database query. At this time this is a SQL query returning a table so the data property can just be an array of records holding the values of the variables.
@TODO