fiware / specifications

:clipboard: Open API specifications for FIWARE Generic Enablers

Open API Specifications

This repository contains the Open API / Swagger specifications for the following FIWARE Generic Enablers:

• NGSI v2 API
• NGSI-LD API
• STH Comet API
• QuantumLeap API
• IoT Agent library
• Wirecloud API
• Keyrock API

The OpenAPI folder contains the raw Open API specification JSON files.

---

License

MIT © FIWARE Foundation e.V.

specifications's Issues

Open API spec files

The repository is logical place to look for Open API spec (yaml) files for all the FIWARE standardized APIs. Yet there's currently none. If the files are not collected here, then at least add to readme where the files are.

Document the usage of Gavel Specs

I expect

The documentation reference the usage of Gavel specifications

OpenAPI v3 spec files

I wish

To find OpenAPI V3 spec files

Instead

I just find Swagger V2 spec files ;)

Notes

if you need support in the conversion, I could help!

Full documentation of this API

Our goal is to build up a context driven IoT platform for energy management.
For this I'm trying to understand the NGSIv2 API for a couple of days now. But this is very difficult. Every example I can find (including the step by step guide) lacks some important points.
The main problem (for now) is that I have to register serveral devices, which are able to execute commands. Until now I haven't found any description/example how to do this.
What I've understand so far is:

• the devices will act as context-provider
• for this I have to implement kinds of iot-agents (transform data from/to context-broker and device)
• these iot-agents have to provide the REST endpoints /v2/op/update and /v2/op/query
• on startup they have to use the /v2/registration endpoint of the context-broker to self register
• ....

... and there isn't any description of the registration payload. I don't know how to notify the context-broker about: "Hey CB. I'm device .... I'm able to execute these commands: ...."

Can you please update your documentation/examples.

The swagger instance is offline

The links in the readme do not open right now.

FIWARE-NGSI v2 Swagger Specification - omissions for working with subscriptions

I get an empty set when trying to request a subscription list as documented here https://swagger.lab.fiware.org/#/Subscriptions/List%20Subscriptions:

$ curl -i --insecure -X GET 'https://localhost/v2/subscriptions' -H 'X-Auth-token: 577...82b'

HTTP/2 200
server: nginx/1.18.0 (Ubuntu)
date: Thu, 11 Nov 2021 12:26:22 GMT
content-type: application/json
content-length: 2
fiware-correlator: 94aaac08-42ea-11ec-a8c9-0242ac1d0006
strict-transport-security: max-age=63072000
[]

If we add the fiware-servicepath and fiware-service headers the problem is resolved.

Maybe useful to add to the Swagger spec for the future? I think I was caught out with the same issue some months ago too.

Question: how to contribute suggestion to fiware openapi specs?

Questions:

• @jason-fox @fgalan on which repo can I contribute / PR to fiware openapi specs?
• are those specs just the autosync/conversion from another source?