From 7e40d030540f6a87feaf160db856a15b9ede64f6 Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Fri, 18 Oct 2019 13:12:08 +0200 Subject: [PATCH 1/2] Template service description. --- ...io.bancaditalia.it_terzevalute-wf-web.yaml | 312 ++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml 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..7cb25b4 --- /dev/null +++ b/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml @@ -0,0 +1,312 @@ +# +# 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' + '429': + $ref: '#/components/responses/429TooManyRequests' + '503': + $ref: '#/components/responses/503ServiceUnavailable' + default: + $ref: '#/components/responses/default' + +openapi: 3.0.0 +info: + version: "1.0.0" + # 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: |- + Terze Valute 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: Ritorna i tassi di cambio. + 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: Ritorna i tassi di cambio. + 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: + 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 + 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' + 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' From 74b451a4ac19e323aa87759a3a70ac769cd2ffcc Mon Sep 17 00:00:00 2001 From: Roberto Polli Date: Fri, 18 Oct 2019 13:25:51 +0200 Subject: [PATCH 2/2] update --- ...io.bancaditalia.it_terzevalute-wf-web.yaml | 38 ++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml b/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml index 7cb25b4..f7aa487 100644 --- a/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml +++ b/external-apis/tassidicambio.bancaditalia.it_terzevalute-wf-web.yaml @@ -15,6 +15,8 @@ x-commons: common-responses: &common-responses '400': $ref: '#/components/responses/400BadRequest' + '408': + $ref: '#/components/responses/408RequestTimeout' '429': $ref: '#/components/responses/429TooManyRequests' '503': @@ -24,12 +26,12 @@ x-commons: openapi: 3.0.0 info: - version: "1.0.0" + 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: |- - Terze Valute API. + Tassi di Cambio - REST API. x-summary: >- Renderizza in JSON i dati presenti nei vocabolari controllati. description: | @@ -109,7 +111,7 @@ servers: paths: /latestRates: get: - summary: Ritorna i tassi di cambio. + summary: Ultimi Cambi. description: | Ritorna i tassi di cambio. operationId: get_latest_rates @@ -132,7 +134,7 @@ paths: $ref: '#/components/schemas/LatestResponse' /dailyRates: get: - summary: Ritorna i tassi di cambio. + summary: Cambi Giornalieri. description: | Ritorna i tassi di cambio. operationId: get_daily_rates @@ -160,6 +162,11 @@ paths: 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: @@ -177,10 +184,29 @@ components: 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: @@ -204,6 +230,8 @@ components: $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'