1. Home
  2. TC5.18 - Snap4City API are documented in Swagger, and tested in Postman

TC5.18 - Snap4City API are documented in Swagger, and tested in Postman

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:

 

The Internal Snap4City APIs include:

 

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:

 

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:

 

Testing API with Postman.

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:

  • Share