Test Case Title |
TC5.18 - Snap4City API are documented in Swagger, and tested in Postman |
Goal |
I can: Access to documenting of Snap4City API in Swagger. Access to the testing engine of the Snap4City API in Postman. |
Prerequisites |
Access to internet to get access at documentation in Swagger and testing in Postman. The following functionalities are available only for specific Snap4city users with specific privileges. |
Expected successful result |
Evidence of the fact that Snap4City API are well documented and tested. |
Steps |
The Snap4City API are divided in two main areas:
- Internal: the API that are used for communication among the modules of the platform
- https://www.km4city.org/swagger/internal/index.html
- snap4city.org --> Development Tools --> Docs: Swagger Internal API
- External: the API which are used to communicate with mobiles Applications, devices, third party elements and services, etc.
- https://www.km4city.org/swagger/external/index.html
- snap4city.org --> Development Tools --> Docs: Swagger External API
The Internal Snap4City APIs include:
- IOT device registration API: registration of the devices from the IOT devices itself. The devices can be registered from IOT Applications in NodeRED or directly from the IOT Directory, also accessible as IOT MicroServices block for IOT Applications
- Notificator API: to get informed about notifications defined in the Notificator and City Dashboard, also accessible as IOT MicroServices block for IOT Applications
- DISCES Scheduler API: for monitoring and controlling back office processes of data ingestion and analytics, also accessible as IOT MicroServices block for IOT Applications, for developers
- Resource Manager API, also called ProcessLoader API: they can be used to save and search Resources managed by the Resource Manager (https://processloader.snap4city.org ), they can be IOT Applications, ETL processes, Data Analytics Processes, Dashboard, etc. They can be saved and retrieve from the API so that the other tools can use the Resource Manager as show case of their instances, to share and promote they work.
- Sensor API which is a strange name for their nature. In effect, these are API that the mobile phone and other devices can use to communicate to the back office about their status, position, etc. It is also used to get back suggestions, hints, assistance, soundages, etc.
- Event Logger API: which allow to log any traffic flow data into a common repository for traffic back office analysis and AMMA dashboard.
- Ownership API: a service for registering the user ownerships of the Snap4City resources, data, IoT devices, dashboard, IOT applications, microservices, dashboard, etc.
- Data manager API: data management API, to save personal data into the safer as “MyPersonalData”, “MyAnnotations”, “keys and info of the peripheral devices”, etc.
The external APIs, also called Snap4City Smart City API include:
The set of Snap4City API includes the following main API that may have a value for the city developers:
- Advanced Smart City API described in mode details below. These APIs are also accessible as IOT MicroServices block for IOT Applications as described in https://www.km4city.org/iot-micro-doc/user.html, and https://www.km4city.org/iot-micro-doc/index.html
- Km4City Web App API, also called MicroApplications, these applications can be called as API Rest as well and can be integrated into City Dashboards, so that directly from the Dashboard Builder and/or from the IOT applications you create
The Advanced Smart City API can be used to develop Web (HTML5) and Mobile Apps and provides support for a number of services:
- Search data: by text, near, along line, POI, etc. resolving text to GPS and formal city nodes model, resolving from GPS to street civic number, etc.
- Empowering the city users: collecting data from end users’ bidirectional data flow; votes, comments, images;
- Access to event information provided that they are loaded into the storage with some ETL or NodeRED process;
- accessing to info and service on Public Mobility: busstops, public transport lines (bus, train, and ferry), public routes, public transport position, arrival time, etc.;
- accessing to info and service on Private Mobility: routing, parking recovery;
- accessing to Cultural and Touristic information, POI;
- accessing to health services & Environmental info;
- requesting routing: car, vehicle, multimodal exploiting pedestrian and any public transport, if any;
- requesting Suggestions;
- requesting Personal Assistant hints, provided that you have an Assistant installed in the solution;
- subscription/request of a Snap4City Applications;
- Sharing knowledge among cities
- providing feedback about services
- IOT device Discovery
- IOT sensor/actuator Discovery by ValueType and/or ValueUnit
The swagger of the Smap4City Smart City API is:
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: https://documenter.getpostman.com/view/4177198/km4city-api/RW83QsX5
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/docs/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/
- 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