diff --git a/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml b/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml new file mode 100644 index 0000000..f7aa487 --- /dev/null +++ b/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml @@ -0,0 +1,340 @@ +# +# Questo e' un progetto d'esempio in formato OpenAPI 3.0 API Starter Kit. +# +# Stai per sviluppare un API? Segui attentamente questo template e +# potrai integrarla facilmente in Developers Italia. +# +x-commons: + ratelimit-headers: &ratelimit-headers + X-RateLimit-Limit: + $ref: '#/components/headers/X-RateLimit-Limit' + X-RateLimit-Remaining: + $ref: '#/components/headers/X-RateLimit-Remaining' + X-RateLimit-Reset: + $ref: '#/components/headers/X-RateLimit-Reset' + common-responses: &common-responses + '400': + $ref: '#/components/responses/400BadRequest' + '408': + $ref: '#/components/responses/408RequestTimeout' + '429': + $ref: '#/components/responses/429TooManyRequests' + '503': + $ref: '#/components/responses/503ServiceUnavailable' + default: + $ref: '#/components/responses/default' + +openapi: 3.0.0 +info: + version: "draft" + # Il `title` e' il nome del tuo prodotto/servizio! + # E' la prima cosa ad apparire in pagine web e cataloghi. + # Dev'essere chiaro e conciso. + title: |- + Tassi di Cambio - REST API. + x-summary: >- + Renderizza in JSON i dati presenti nei vocabolari controllati. + description: | + #### Documentazione + Il nuovo dominio base per i servizi A2A è: + + https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0 + + Per brevità nella descrizione delle URL si omette il dominio base. + Quindi, ad esempio, invece di + + GET https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0/currencies + + scriviamo semplicemente GET /currencies + Oppure al posto di + + GET https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0/latestRates?lang={} + + scriviamo solo GET /latestRates?lang={} + + I parametri in input ripetibili sono indicati nell'URL tra parentesi quadre. Ad esempio come in: + + GET /dailyRates?referenceDate={}[&baseCurrencyIsoCode={}]¤cyIsoCode={}&lang={} + + ##### Sottosezioni + E' possibile utilizzare - con criterio - delle sottosezioni. + + #### Note + + Il servizio non richiede autenticazione, ma va' usato rispettando gli + header di throttling esposti in conformita' alle Linee Guida del Modello di interoperabilita'. + + #### Informazioni tecniche ed esempi + + Esempio: + + + + # I termini del servizio contengono un riferimento + # a tutte le indicazioni e le note legali per l'utilizzo + # del servizio, inclusi gli eventuali riferimenti utili al GDPR. + termsOfService: 'http://swagger.io/terms/' + # Chi posso contattare per informazioni sul servizio e sul suo stato? + contact: + name: Banca d'Italia + url: https://tassidicambio.bancaditalia.it + # L'audience delle API. Attualmente e' definito solamente + # la tipologia `public`. + x-audience: + - public + # Ogni API deve avere un UUID, invariante nel tempo e + # rispetto al `title`. + x-api-id: 00000000-0000-0000-0000-000000000000 + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' +externalDocs: + url: https://www.bancaditalia.it/compiti/operazioni-cambi/Nuove_Istruzioni_tecnico-operative.pdf + description: Documentazione ufficiale +# Una lista di `tag` utili a raggruppare le varie operazioni +# eseguite dalle API. Ogni `tag` puo' referenziare un link +# alla sua descrizione. +tags: + - name: public + description: Retrieve informations + externalDocs: + url: http://docs.my-api.com/pet-operations.htm +# Uno o piu' server di erogazione. +# Puo' essere utile indicare gli indirizzi di collaudo, +# sviluppo e test. +servers: + - description: Production + url: https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0 +# +# Qui vanno tutti i path. +# +paths: + /latestRates: + get: + summary: Ultimi Cambi. + description: | + Ritorna i tassi di cambio. + operationId: get_latest_rates + tags: + - public + parameters: + - $ref: '#/components/parameters/lang' + responses: + <<: *common-responses + '200': + description: | + Ultimi cambi ritornati correttamente. + # Questi header di throttling sono obbligatori e definiti + # nel Nuovo modello di interoperabilità. + headers: + <<: *ratelimit-headers + content: + application/json: + schema: + $ref: '#/components/schemas/LatestResponse' + /dailyRates: + get: + summary: Cambi Giornalieri. + description: | + Ritorna i tassi di cambio. + operationId: get_daily_rates + tags: + - public + parameters: + - $ref: '#/components/parameters/lang' + - $ref: '#/components/parameters/currencyIsoCode' + - $ref: '#/components/parameters/referenceDate' + + responses: + <<: *common-responses + '200': + description: | + Cambi giornalier ritornati correttamente. + # Questi header di throttling sono obbligatori e definiti + # nel Nuovo modello di interoperabilità. + headers: + <<: *ratelimit-headers + content: + application/json: + schema: + $ref: '#/components/schemas/DailyResponse' + +components: + parameters: + lang: + description: |- + Stringa identificativa della lingua in cui si desidera ottenere i dati: può valere “it” o “en” + case insensitive. + Se il parametro non viene specificato, o valorizzato in modo errato, i risultati saranno + forniti nella lingua di default. + name: lang + in: query + schema: + type: string + enum: + - it + - en + example: it + referenceDate: + name: referenceDate + in: query + schema: + type: string + format: date + example: 2011-01-23 + currencyIsoCode: + name: currencyIsoCode + description: | + Codice ISO (case insensitive) della valuta "contro" cui si vuole la + quotazione. Può valere “EUR”, “USD”, “ITL”. Se il parametro non è + specificato, o è specificato un valore diverso da quelli validi, il servizio + restituirà un messaggio di errore + in: query + schema: + $ref: https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/schemas/CurrencyCode + baseCurrencyIsoCode: + name: baseCurrencyIsoCode + description: | + Codice ISO (case insensitive) della valuta per cui si richiede la quotazione. + Nel caso di più valute il parametro sarà ripetuto. Se il parametro non + viene passato, si intendono tutte le valute per cui è disponibile la + quotazione nella data richiesta. + Codici ISO inesistenti verranno scartati. Se tutti i codici ISO inseriti sono + inesistenti, verrà restituita una lista vuota. + Se il parametro è specificato in un formato errato, il servizio restituirà un + messaggio di errore. + in: query + schema: + $ref: https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/schemas/CurrencyCode + + headers: + Cache-Control: + schema: + type: string + X-RateLimit-Limit: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/headers/X-RateLimit-Limit' + X-RateLimit-Remaining: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/headers/X-RateLimit-Remaining' + X-RateLimit-Reset: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/headers/X-RateLimit-Reset' + Retry-After: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/headers/Retry-After' + + responses: + # Predefined error codes for this API + 400BadRequest: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/400BadRequest' + 404NotFound: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/404NotFound' + 429TooManyRequests: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/429TooManyRequests' + 503ServiceUnavailable: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/503ServiceUnavailable' + 408RequestTimeout: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/default' + default: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/responses/default' + + schemas: + DailyResponse: + properties: + resultsInfo: + $ref: '#/components/schemas/ResultsInfo' + rates: + type: array + items: + $ref: '#/components/schemas/CurrencyAverageRate' + + LatestResponse: + properties: + resultsInfo: + $ref: '#/components/schemas/ResultsInfo' + latestRates: + type: array + items: + $ref: '#/components/schemas/CurrencyRate' + ResultsInfo: + description: | + $schema: 'http://json-schema.org/draft-04/schema#' + type: object + properties: + notice: + type: string + timezoneReference: + type: string + totalRecords: + type: integer + required: + - notice + - timezoneReference + - totalRecords + + CurrencyAverageRate: + description: |- + "$schema": 'http://json-schema.org/draft-04/schema#' + type: object + properties: + country: + type: string + currency: + type: string + isoCode: + type: string + referenceDate: + type: string + uicCode: + type: string + exchangeConvention: + type: string + exchangeConventionCode: + type: string + avgRate: + type: string + required: + - country + - currency + - isoCode + - uicCode + - referenceDate + - avgRate + - exchangeConvention + - exchangeConventionCode + + + CurrencyRate: + description: |- + "$schema": 'http://json-schema.org/draft-04/schema#' + type: object + properties: + country: + type: string + currency: + type: string + eurRate: + type: string + isoCode: + type: string + referenceDate: + type: string + uicCode: + type: string + usdExchangeConvention: + type: string + usdExchangeConventionCode: + type: string + usdRate: + type: string + required: + - country + - currency + - isoCode + - uicCode + - referenceDate + + - eurRate + - usdExchangeConvention + - usdExchangeConventionCode + - usdRate + + Problem: + $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/schemas/Problem'