Snap4city API on Postman: https://documenter.getpostman.com/view/4177198/km4city-api/RW83QsX5
Postman (https://www.getpostman.com/) comes in the form of a standalone application that can be used for invoking APIs and investigating the responses. When configuring an invocation, the API URL, the HTTP method, the request headers, and the request body can be filled in through an appropriate interface that also embed assisted input functionalities. The interface makes it easy to provide both unstructured (raw) and structured request bodies (such as the set of the parameters that make up the query string of an HTTP GET request, or the set of the POST parameters to emulate the sending of an HTTP Form via POST). Once a response is provided to the API invocation, the Postman application allows to seamlessly inspect the response code, headers and body. The request/response pair can be persisted as a so-called sample, that could be loaded on a Postman server so that it could be leveraged by a front-end developer for making sample calls and getting sample responses even before that the API development is completed. Request can be persisted also without a sample response associated, and can be organized in so-called collections, structured sets of API invocations that can be enriched with descriptive metadata and loaded on a Postman server so that they could be accessed by everybody through the Internet to get informed about what invocations can be done with what parameters, and for performing real-time invocations. The APIs that are grouped in a collection also can be executed in bulk for monitoring purposes. The bulk execution of the APIs that are wrapped in a collection also can be scheduled, and it is automatically executed by Postman. A certain degree of integration also can be observed of Postman with other notable tools and projects for API specification, documentation, development and testing, such as the possibility of importing a Swagger specification instead of adding all the requests by hand.
For the purposes of our project, the Postman has been leveraged for the creation of a collection of all the read-only APIs that are currently stable and publicly available. The collection is partitioned into nine sections, for a total of 153 requests:
- Discovery of services, with sample calls to APIs that allow to discover the available services, and retrieve some minimal information about each of them, including the Service URI, that can be leveraged for requesting further details through calls like those that can be found in the Details about services section (see below);
- Discovery of events, POIs, etc. with sample calls to APIs that allow to discover the scheduled events, the Points Of Interest (POI), the roads and street numbers, and so on, and retrieve some minimal information about each of such entities, including the Service URI, that can be leveraged for requesting further details through calls like those that can be found in the Details about services section (see below);
- Details about services, with sample calls for requesting full details about a specific Service identified through its Service URI. Different types of service have different details;
- Public transport, with sample calls to APIs that allow to retrieve both structural and real-time information about the public transport, such as the available agencies, lines, routes, stops, and some estimation about the position of the running buses;
- User feedbacks, it should be noted anyway that the widest part of the APIs that relates to the user feedbacks expectedly write the contributions that come from the user themselves, and they are therefore kept away from the collection. Instead, a sample call is provided for the retrieval of the most recent user feedbacks;
- Recommender, that includes a sample call to the Recommender, the component that provides suggestions to the users about the services that they could be interested in, based on the user position, and possibly on the user habits;
- DISCES, that includes some sample calls to the DISCES (DISTRIBUTED SMART CITY/CLOUD ENGINE SCHEDULER) APIs, that are focused on the management of the software processes. Expectedly, the largest part of these APIs performs some sort of writing or status modification, and it is therefore kept away from the collection. Nevertheless, sample calls are provided for those APIs that allow to retrieve the status of the different entities without performing any modification;
- Web App, where a set can be found of sample calls to the APIs that are leveraged by the Km4City mobile applications (Android, iOS, Windows, Web);
- Control Room, where a set can be found of sample calls to the APIs that are leveraged for populating the dashboards that are thought to be displayed in the control rooms, and for triggering and catching a comprehensive set of events of interest.
For each request, the following is provided:
- The API name;
- The supported HTTP method(s);
- A sample request/response pair;
- An exhaustive description of the API context and purpose;
- The full listing of the mandatory and optional parameters, each including a sample value and a short description including the parameter motivation, its impact, and the expected data type and formatting in the most general case;
- References to external documentation.
The Postman Collection of the Km4City/Snap4City APIs is publicly available and can be reached at the following URL:
There, not only all the mentioned information can be found for each of the provided sample requests, but sample code for many of the most commonly used programming languages such as jQuery, Ruby, Python, Node, PHP, Go and sample cURL commands can be found for a seamless invocation of the APIs with custom input parameters.
Snap4City Smart City API:
- Advanced Smart City API: https://www.snap4city.org/download/video/Km4City_Smart_City_API_Guideline_version_1_Sii-Mobility.pdf
- Tutorial for App developers using Advanced Smart City API: https://www.disit.org/7044
- Documentation in Swagger: https://www.km4city.org/swagger/external/index.html and https://www.km4city.org/swagger/internal/index.html
- Testing in Postman: https://documenter.getpostman.com/view/4177198/km4city-api/RW83QsX5
- Web page here on testing Snap4City API: https://www.snap4city.org/drupal/node/70