|
|
home |
|
|
\ No newline at end of file |
|
|
Este caso de uso permite el envío por parte de los suministradores de la información en tiempo real de la disponibilidad plazas de aparcamiento.
|
|
|
|
|
|
The platform has two different functionalities for the **publication (sending)** and for the **subscription (reception)** of information. The first is through a REST API and the second through a real-time MQTT service.
|
|
|
|
|
|
Both the publication and subscription functionality require different access certificates that must be requested and supplied by DGT 3.0. If these certificates have not already been requested, they should be requested from *[soporte@cmobility30.es](mailto:soporte@cmobility30.es)*.
|
|
|
|
|
|
Below are the URLs with which each functionality is accessed:
|
|
|
|
|
|
| Mode | URL | Description |
|
|
|
| ------------ | -------------------------------------- | ------------------------------------------------------ |
|
|
|
| Publication | https://pre.cmobility30.es/use-case-11 | Client integration environment endpoint for publishing |
|
|
|
| Subscription | mqtt://mqtt.pre.cmobility30.es:8883 | Integration environment endpoint for subscription |
|
|
|
|
|
|
The two functionalities are described below.
|
|
|
|
|
|
## Publication
|
|
|
|
|
|
This use case has a REST API for the publication (sending) of the data by the companies that request it. Details of this can be found in the following sections:
|
|
|
|
|
|
- General details for making a request:
|
|
|
|
|
|
> [General · (cmobility30.es)](https://gitlab.cs.cmobility30.es/dgt3.0_esp/general/-/wikis/home)
|
|
|
|
|
|
- Information regarding the event to be sent:
|
|
|
|
|
|
> [Event](publicacion/Event)
|
|
|
|
|
|
## Subscription
|
|
|
|
|
|
This use case also has a subscription service (reception) to the data for the companies that request it through the MQTT protocol. Below you can find the details of this:
|
|
|
|
|
|
**MQTT (MQ Telemetry Transport)** is a messaging protocol used as a simple and lightweight method to transfer data to / from low-power devices.
|
|
|
|
|
|
The protocol supports a single messaging pattern, the **Publish-Subscribe** pattern: each message is published on a topic that must be subscribed to in order to receive the information.
|
|
|
|
|
|
Subscription to the service of this use case must be through the topic:
|
|
|
|
|
|
> usecase11/events
|
|
|
|
|
|
In the topic, the events are published in JSON format. Here you can see an example:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"municipalityIneCode":50297,
|
|
|
"parkingId":1,
|
|
|
"freeCapacity":4,
|
|
|
"totalCapacity":5
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- municipalityIneCode (integer): identifier of the municipality where the event is generated according to [INE](https://www.ine.es/daco/daco42/codmun/cod_provincia_estandar.htm)
|
|
|
|
|
|
- parkingId (integer): parking identifier
|
|
|
|
|
|
- freeCapacity (integer): number of free parking spaces
|
|
|
|
|
|
- totalCapacity (integer): total parking capacity
|
|
|
|
|
|
See more information and a connection example [here](https://gitlab.cs.cmobility30.es/dgt3.0_eng/general/-/wikis/MQTT).
|
|
|
|
|
|
## Errors
|
|
|
|
|
|
As stated above, all HTTP responses other than **200 – OK**, can be considered **invalid**. The format of the error response is like the following example:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": 401,
|
|
|
"code": 1,
|
|
|
"message": "User not found or valid"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
These errors will have three main categories:
|
|
|
|
|
|
#### Authentication Error
|
|
|
|
|
|
- HTTP Status: **401 - Unauthorized**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | ----------------------- |
|
|
|
| 1 | User not found or valid |
|
|
|
|
|
|
#### Client Error
|
|
|
|
|
|
- HTTP Status: **400 - Bad Request**
|
|
|
|
|
|
- | Code | Message |
|
|
|
| ---- | ------------------------------------------------------------------- |
|
|
|
| 0 | Authenticate |
|
|
|
| 2 | Entity ID not found |
|
|
|
| 3 | Missing required property |
|
|
|
| 4 | The entity received cannot be proccessed |
|
|
|
| 5 | Incorrect token received |
|
|
|
| 6 | Expired token received |
|
|
|
| 7 | There is an error with the token provided. Please request a new one |
|
|
|
| 8 | No token received |
|
|
|
| 9 | Required request body is missing |
|
|
|
| 10 | Event is marked as expired by timestamp |
|
|
|
| 11 | Missing request header |
|
|
|
| 12 | Access denied role |
|
|
|
| 13 | Unique key violated |
|
|
|
| 14 | There is an error in one or more elements |
|
|
|
| 15 | Free capacity should not be greater than total capacity |
|
|
|
| 16 | Invalid GeoJson |
|
|
|
| 17 | GeoJson does not belong to municipality |
|
|
|
|
|
|
In the case of getting an error *3 - Missing required property*, the response obtained will have a value in the message that will indicate the missing fields to send:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": 400,
|
|
|
"code": 3,
|
|
|
"message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### Server error
|
|
|
|
|
|
- HTTP Status: **500 - Internal Server Error**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | -------------- |
|
|
|
| 18 | Internal error | |
|
|
\ No newline at end of file |