From 330440dbe59168c558f4e146a645cd9c87598395 Mon Sep 17 00:00:00 2001 From: Raimundo Henriques Date: Tue, 14 May 2024 16:37:42 +0100 Subject: [PATCH] chore: update openapi.json files and README --- spec/rest-api/README.md | 7 +- ...api-2.2.0-wip1.json => openapi-2.2.0.json} | 2 +- spec/rest-api/openapi-2.2.1-wip.json | 977 ++++++++++++++++++ 3 files changed, 981 insertions(+), 5 deletions(-) rename spec/rest-api/{openapi-2.2.0-wip1.json => openapi-2.2.0.json} (99%) create mode 100644 spec/rest-api/openapi-2.2.1-wip.json diff --git a/spec/rest-api/README.md b/spec/rest-api/README.md index 8c4a68d..a523473 100644 --- a/spec/rest-api/README.md +++ b/spec/rest-api/README.md @@ -1,8 +1,6 @@ # specs/rest-api -Here we are distributing OpenAPI files which describe the Use Case 001 REST API. - -**⚠️⚠️ Right now, the OpenAPI files here are work in progress and pending a through review from the Pathfinder community. ⚠️⚠️** +Here we are distributing OpenAPI files which describe an HTTP REST API conformant to the PACT Technical Specifications. ## OpenAPI file lineage @@ -14,4 +12,5 @@ You can regenerate the files by building and running the [endpoint](../../endpoi | :---------------------------------------: | :--------: | ------------------------------------------------ | | [`1.0.0-beta1`](openapi-1.0.0-beta1.json) | 2022-06-16 | Initial version imported for comments and review | | [`1.0.0-beta2`](openapi-1.0.0-beta2.json) | 2023-01-06 | Updated version (incorporating Mikito Iwamasa's feedback. Thank you!) | -| [`2.2.0-20240327`](openapi-2.2.0-wip1.json) | 2024-04-30 | Version 2.2.0 of the tech specs (to be community-reviewed) | \ No newline at end of file +| [`2.2.0-20240327`](openapi-2.2.0.json) | 2024-04-30 | Version 2.2.0 of the tech specs (reviewed) | +| [`2.2.1-20240514`](openapi-2.2.1-wip.json) | 2024-05-14 | Version 2.2.1 of these tech specs (reviewed) | diff --git a/spec/rest-api/openapi-2.2.0-wip1.json b/spec/rest-api/openapi-2.2.0.json similarity index 99% rename from spec/rest-api/openapi-2.2.0-wip1.json rename to spec/rest-api/openapi-2.2.0.json index ce05a8e..e255e30 100644 --- a/spec/rest-api/openapi-2.2.0-wip1.json +++ b/spec/rest-api/openapi-2.2.0.json @@ -1048,4 +1048,4 @@ } } } -} \ No newline at end of file +} diff --git a/spec/rest-api/openapi-2.2.1-wip.json b/spec/rest-api/openapi-2.2.1-wip.json new file mode 100644 index 0000000..222162d --- /dev/null +++ b/spec/rest-api/openapi-2.2.1-wip.json @@ -0,0 +1,977 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "pathfinder-endpoint", + "version": "2.2.1-wip1" + }, + "paths": { + "/2/footprints/{id}": { + "get": { + "operationId": "get_pcf", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/PfId" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductFootprintResponse" + } + } + } + }, + "400": { + "description": "# 400 Bad Request\nThe request given is wrongly formatted or data was missing. ", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequest" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/2/footprints": { + "get": { + "operationId": "get_footprints", + "parameters": [ + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + }, + { + "name": "$filter", + "in": "query", + "description": "Syntax as defined by the ODatav4 specification", + "allowEmptyValue": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "headers": { + "link": { + "description": "Link header to next result set. See Tech Specs section 6.6.1", + "schema": { + "type": "string" + }, + "example": "https://api.example.com/2/footprints?[...]" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PfListingResponseInner" + } + } + } + }, + "400": { + "description": "# 400 Bad Request\nThe request given is wrongly formatted or data was missing. ", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequest" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/2/events": { + "post": { + "operationId": "post_event", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathfinderEvent" + } + } + } + }, + "responses": { + "200": { + "description": "" + }, + "400": { + "description": "# 400 Bad Request\nThe request given is wrongly formatted or data was missing. ", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequest" + } + } + } + }, + "403": { + "description": "# 403 Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessDenied" + } + } + } + }, + "501": { + "description": "# 501 Not Implemented\nThe request given is not implemented by the server. ", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequest" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ProductFootprintResponse": { + "description": "HTTP Body of Action `GetFootprint`", + "type": "object", + "required": ["data"], + "properties": { + "data": { + "$ref": "#/components/schemas/ProductFootprint" + } + } + }, + "ProductFootprint": { + "description": "Data Type \"ProductFootprint\" of Tech Spec Version 2", + "type": "object", + "required": [ + "comment", + "companyIds", + "companyName", + "created", + "id", + "pcf", + "productCategoryCpc", + "productDescription", + "productIds", + "productNameCompany", + "specVersion", + "status", + "version" + ], + "properties": { + "id": { + "$ref": "#/components/schemas/PfId" + }, + "specVersion": { + "$ref": "#/components/schemas/VersionString" + }, + "precedingPfIds": { + "allOf": [ + { + "$ref": "#/components/schemas/NonEmptyPfIdVec" + } + ], + "nullable": true + }, + "version": { + "$ref": "#/components/schemas/VersionInteger" + }, + "created": { + "type": "string", + "format": "date-time" + }, + "updated": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "status": { + "$ref": "#/components/schemas/PfStatus" + }, + "statusComment": { + "type": "string", + "nullable": true + }, + "validityPeriodStart": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "validityPeriodEnd": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "companyName": { + "$ref": "#/components/schemas/NonEmptyString" + }, + "companyIds": { + "$ref": "#/components/schemas/CompanyIdSet" + }, + "productDescription": { + "type": "string" + }, + "productIds": { + "$ref": "#/components/schemas/ProductIdSet" + }, + "productCategoryCpc": { + "$ref": "#/components/schemas/NonEmptyString" + }, + "productNameCompany": { + "$ref": "#/components/schemas/NonEmptyString" + }, + "comment": { + "type": "string" + }, + "pcf": { + "$ref": "#/components/schemas/CarbonFootprint" + } + } + }, + "PfId": { + "type": "string", + "format": "uuid" + }, + "VersionString": { + "type": "string", + "minLength": 5, + "pattern": "^\\d+\\.\\d+\\.\\d+(-\\d{8})?$" + }, + "NonEmptyPfIdVec": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "uniqueItems": true + }, + "VersionInteger": { + "type": "integer", + "format": "int32", + "maximum": 2147483647, + "minimum": 0 + }, + "PfStatus": { + "type": "string", + "enum": ["Active", "Deprecated"] + }, + "NonEmptyString": { + "type": "string", + "minLength": 1 + }, + "CompanyIdSet": { + "type": "array", + "items": { + "type": "string", + "pattern": "^([uU][rR][nN]):" + }, + "minItems": 1, + "uniqueItems": true + }, + "GenericURN": { + "type": "string", + "pattern": "^([uU][rR][nN]):" + }, + "ProductIdSet": { + "type": "array", + "items": { + "type": "string", + "pattern": "^([uU][rR][nN]):" + }, + "minItems": 1, + "uniqueItems": true + }, + "CarbonFootprint": { + "description": "Data Type \"CarbonFootprint\" of Spec Version 2", + "type": "object", + "anyOf": [ + { + "type": "null" + }, + { + "type": "object", + "required": ["geographyRegionOrSubregion"], + "properties": { + "geographyRegionOrSubregion": { + "$ref": "#/components/schemas/UNRegionOrSubregion" + } + } + }, + { + "type": "object", + "required": ["geographyCountry"], + "properties": { + "geographyCountry": { + "$ref": "#/components/schemas/ISO3166CC" + } + } + }, + { + "type": "object", + "required": ["geographyCountrySubdivision"], + "properties": { + "geographyCountrySubdivision": { + "$ref": "#/components/schemas/NonEmptyString" + } + } + } + ], + "required": [ + "biogenicCarbonContent", + "boundaryProcessesDescription", + "characterizationFactors", + "crossSectoralStandardsUsed", + "declaredUnit", + "exemptedEmissionsDescription", + "exemptedEmissionsPercent", + "fossilCarbonContent", + "fossilGhgEmissions", + "ipccCharacterizationFactorsSources", + "pCfExcludingBiogenic", + "packagingEmissionsIncluded", + "productOrSectorSpecificRules", + "referencePeriodEnd", + "referencePeriodStart", + "unitaryProductAmount" + ], + "properties": { + "declaredUnit": { + "$ref": "#/components/schemas/DeclaredUnit" + }, + "unitaryProductAmount": { + "$ref": "#/components/schemas/StrictlyPositiveDecimal" + }, + "pCfExcludingBiogenic": { + "$ref": "#/components/schemas/PositiveDecimal" + }, + "pCfIncludingBiogenic": { + "allOf": [ + { + "$ref": "#/components/schemas/Decimal" + } + ], + "nullable": true + }, + "fossilGhgEmissions": { + "$ref": "#/components/schemas/PositiveDecimal" + }, + "fossilCarbonContent": { + "$ref": "#/components/schemas/PositiveDecimal" + }, + "biogenicCarbonContent": { + "$ref": "#/components/schemas/PositiveDecimal" + }, + "dLucGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "landManagementGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "otherBiogenicGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "iLucGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "biogenicCarbonWithdrawal": { + "allOf": [ + { + "$ref": "#/components/schemas/NegativeDecimal" + } + ], + "nullable": true + }, + "aircraftGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "characterizationFactors": { + "$ref": "#/components/schemas/CharacterizationFactors" + }, + "ipccCharacterizationFactorsSources": { + "$ref": "#/components/schemas/IpccCharacterizationFactorsSources" + }, + "crossSectoralStandardsUsed": { + "$ref": "#/components/schemas/CrossSectoralStandardSet" + }, + "productOrSectorSpecificRules": { + "$ref": "#/components/schemas/ProductOrSectorSpecificRuleSet" + }, + "biogenicAccountingMethodology": { + "allOf": [ + { + "$ref": "#/components/schemas/BiogenicAccountingMethodology" + } + ], + "nullable": true + }, + "boundaryProcessesDescription": { + "type": "string" + }, + "referencePeriodStart": { + "type": "string", + "format": "date-time" + }, + "referencePeriodEnd": { + "type": "string", + "format": "date-time" + }, + "secondaryEmissionFactorSources": { + "allOf": [ + { + "$ref": "#/components/schemas/EmissionFactorDSSet" + } + ], + "nullable": true + }, + "exemptedEmissionsPercent": { + "$ref": "#/components/schemas/ExemptedEmissionsPercent" + }, + "exemptedEmissionsDescription": { + "type": "string" + }, + "packagingEmissionsIncluded": { + "type": "boolean" + }, + "packagingGhgEmissions": { + "allOf": [ + { + "$ref": "#/components/schemas/PositiveDecimal" + } + ], + "nullable": true + }, + "allocationRulesDescription": { + "type": "string", + "nullable": true + }, + "uncertaintyAssessmentDescription": { + "type": "string", + "nullable": true + }, + "primaryDataShare": { + "allOf": [ + { + "$ref": "#/components/schemas/Percent" + } + ], + "nullable": true + }, + "dqi": { + "allOf": [ + { + "$ref": "#/components/schemas/DataQualityIndicators" + } + ], + "nullable": true + }, + "assurance": { + "allOf": [ + { + "$ref": "#/components/schemas/Assurance" + } + ], + "nullable": true + } + } + }, + "DeclaredUnit": { + "description": "Data Type \"DeclaredUnit\" of Spec Version 2", + "type": "string", + "enum": [ + "liter", + "kilogram", + "cubic meter", + "kilowatt hour", + "megajoule", + "ton kilometer", + "square meter" + ] + }, + "StrictlyPositiveDecimal": { + "type": "string", + "pattern": "^(\\d*[1-9]\\d*([\\.]\\d+)?|\\d+(\\.\\d*[1-9]\\d*)?)$" + }, + "PositiveDecimal": { + "type": "string", + "pattern": "^\\d+(\\.\\d+)?$" + }, + "Decimal": { + "type": "string", + "pattern": "^-?\\d+(\\.\\d+)?$" + }, + "NegativeDecimal": { + "type": "string", + "pattern": "^(-\\d+(\\.\\d+)?)|0$" + }, + "CharacterizationFactors": { + "type": "string", + "enum": ["AR5", "AR6"] + }, + "IpccCharacterizationFactorsSources": { + "type": "array", + "items": { + "type": "string", + "pattern": "^AR\\d+$" + }, + "minItems": 1, + "uniqueItems": true + }, + "IpccCharacterizationFactorsSource": { + "type": "string", + "pattern": "^AR\\d+$" + }, + "CrossSectoralStandardSet": { + "type": "array", + "items": { + "description": "Data Type \"CrossSectoralStandard\" of Spec Version 2", + "type": "string", + "enum": [ + "GHG Protocol Product standard", + "ISO Standard 14067", + "ISO Standard 14044" + ] + }, + "minItems": 1, + "uniqueItems": true + }, + "CrossSectoralStandard": { + "description": "Data Type \"CrossSectoralStandard\" of Spec Version 2", + "type": "string", + "enum": [ + "GHG Protocol Product standard", + "ISO Standard 14067", + "ISO Standard 14044" + ] + }, + "ProductOrSectorSpecificRuleSet": { + "type": "array", + "items": { + "type": "object", + "required": ["operator", "ruleNames"], + "properties": { + "operator": { + "$ref": "#/components/schemas/ProductOrSectorSpecificRuleOperator" + }, + "ruleNames": { + "$ref": "#/components/schemas/NonEmptyStringVec" + }, + "otherOperatorName": { + "allOf": [ + { + "$ref": "#/components/schemas/NonEmptyString" + } + ], + "nullable": true + } + } + }, + "uniqueItems": true + }, + "ProductOrSectorSpecificRule": { + "type": "object", + "required": ["operator", "ruleNames"], + "properties": { + "operator": { + "$ref": "#/components/schemas/ProductOrSectorSpecificRuleOperator" + }, + "ruleNames": { + "$ref": "#/components/schemas/NonEmptyStringVec" + }, + "otherOperatorName": { + "allOf": [ + { + "$ref": "#/components/schemas/NonEmptyString" + } + ], + "nullable": true + } + } + }, + "ProductOrSectorSpecificRuleOperator": { + "type": "string", + "enum": ["PEF", "EPD International", "Other"] + }, + "NonEmptyStringVec": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1, + "uniqueItems": true + }, + "BiogenicAccountingMethodology": { + "type": "string", + "enum": ["PEF", "ISO", "GHPG", "Quantis"] + }, + "EmissionFactorDSSet": { + "type": "array", + "items": { + "type": "object", + "required": ["name", "version"], + "properties": { + "name": { + "$ref": "#/components/schemas/NonEmptyString" + }, + "version": { + "$ref": "#/components/schemas/NonEmptyString" + } + } + }, + "minItems": 1, + "uniqueItems": true + }, + "EmissionFactorDS": { + "type": "object", + "required": ["name", "version"], + "properties": { + "name": { + "$ref": "#/components/schemas/NonEmptyString" + }, + "version": { + "$ref": "#/components/schemas/NonEmptyString" + } + } + }, + "ExemptedEmissionsPercent": { + "type": "number", + "format": "double", + "maximum": 5, + "minimum": 0 + }, + "Percent": { + "type": "number", + "format": "double", + "maximum": 100, + "minimum": 0 + }, + "DataQualityIndicators": { + "description": "Data Type \"DataQualityIndicators\" of Spec Version 2", + "type": "object", + "required": [ + "completenessDQR", + "coveragePercent", + "geographicalDQR", + "reliabilityDQR", + "technologicalDQR", + "temporalDQR" + ], + "properties": { + "coveragePercent": { + "$ref": "#/components/schemas/Percent" + }, + "technologicalDQR": { + "$ref": "#/components/schemas/FloatBetween1And3" + }, + "temporalDQR": { + "$ref": "#/components/schemas/FloatBetween1And3" + }, + "geographicalDQR": { + "$ref": "#/components/schemas/FloatBetween1And3" + }, + "completenessDQR": { + "$ref": "#/components/schemas/FloatBetween1And3" + }, + "reliabilityDQR": { + "$ref": "#/components/schemas/FloatBetween1And3" + } + } + }, + "FloatBetween1And3": { + "type": "number", + "format": "float", + "maximum": 3, + "minimum": 1 + }, + "Assurance": { + "description": "Data Type \"Assurance\" of Spec Version 2", + "type": "object", + "required": ["assurance", "providerName"], + "properties": { + "assurance": { + "type": "boolean" + }, + "coverage": { + "allOf": [ + { + "$ref": "#/components/schemas/AssuranceCoverage" + } + ], + "nullable": true + }, + "level": { + "allOf": [ + { + "$ref": "#/components/schemas/AssuranceLevel" + } + ], + "nullable": true + }, + "boundary": { + "allOf": [ + { + "$ref": "#/components/schemas/AssuranceBoundary" + } + ], + "nullable": true + }, + "providerName": { + "type": "string" + }, + "completedAt": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "standardName": { + "type": "string", + "nullable": true + }, + "comments": { + "type": "string", + "nullable": true + } + } + }, + "AssuranceCoverage": { + "type": "string", + "enum": [ + "corporate level", + "product line", + "PCF system", + "product level" + ] + }, + "AssuranceLevel": { + "type": "string", + "enum": ["limited", "reasonable"] + }, + "AssuranceBoundary": { + "type": "string", + "enum": ["Gate-to-Gate", "Cradle-to-Gate"] + }, + "UNRegionOrSubregion": { + "description": "List of UN regions and subregions", + "type": "string", + "enum": [ + "Africa", + "Americas", + "Asia", + "Europe", + "Oceania", + "Australia and New Zealand", + "Central Asia", + "Eastern Asia", + "Eastern Europe", + "Latin America and the Caribbean", + "Melanesia", + "Micronesia", + "Northern Africa", + "Northern America", + "Northern Europe", + "Polynesia", + "South-eastern Asia", + "Southern Asia", + "Southern Europe", + "Sub-Saharan Africa", + "Western Asia", + "Western Europe" + ] + }, + "ISO3166CC": { + "type": "string" + }, + "BadRequest": { + "description": "Response with an error code of `BadRequest`. See Chapter \"Error Codes\" of the Tech Specs for mor details.", + "type": "object", + "required": ["code", "message"], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "string" + } + } + }, + "PfListingResponseInner": { + "description": "HTTP Body of Action `ListFootprints`", + "type": "object", + "required": ["data"], + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductFootprint" + } + } + } + }, + "AccessDenied": { + "description": "Response with an error code of `AccessDenied`. See Chapter \"Error Codes\" of the Tech Specs for mor details.", + "type": "object", + "required": ["code", "message"], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "string" + } + } + }, + "PathfinderEvent": { + "description": "possible contents of `data` property of events - see tech specs section 6 for details", + "type": "object", + "oneOf": [ + { + "description": "the contents of the `data` field of a `PF Update Event` – see Tech Specs section 6.8.3", + "type": "object", + "required": ["data", "type"], + "properties": { + "type": { + "type": "string", + "enum": ["org.wbcsd.pathfinder.ProductFootprint.Published.v1"] + }, + "data": { + "$ref": "#/components/schemas/PFUpdateEventBody" + } + } + }, + { + "description": "the contents of the `data` field of a `PF Request Event` – see Tech Specs section 6.8.4.1", + "type": "object", + "required": ["data", "type"], + "properties": { + "type": { + "type": "string", + "enum": [ + "org.wbcsd.pathfinder.ProductFootprintRequest.Created.v1" + ] + }, + "data": { + "$ref": "#/components/schemas/PFRequestEventBody" + } + } + } + ], + "required": ["id", "source", "specversion", "time"], + "properties": { + "specversion": { + "type": "string" + }, + "id": { + "type": "string" + }, + "source": { + "type": "string" + }, + "time": { + "type": "string", + "format": "date-time" + } + } + }, + "PFUpdateEventBody": { + "type": "object", + "required": ["pfIds"], + "properties": { + "pfIds": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PfId" + } + } + } + }, + "PFRequestEventBody": { + "type": "object", + "required": ["pf"], + "properties": { + "pf": {}, + "comment": { + "type": "string", + "nullable": true + } + } + } + }, + "securitySchemes": { + "BearerAuth": { + "description": "OAuth2 Client Credentials Grant (RFC6749 4.4)", + "type": "oauth2", + "flows": { + "clientCredentials": { + "tokenUrl": "/2/auth/token", + "scopes": { + "footprint:list": "Ability to list footprints", + "footprint:read": "Ability to access individual footprints" + } + } + } + } + } + } +}