This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "InvestMoz reference catalogues",
|
||||
"version": "1.0.0",
|
||||
"description": "Read-only, rate-limited reference options with stable codes, version metadata and pt-MZ labels. Jurisdictions use the packaged territorial reference set. Economic activities are portal-curated sector groupings, not an official statutory classification. Authority entries are withheld until an authoritative source is approved."
|
||||
},
|
||||
"servers": [{ "url": "/api/v1/catalogs" }],
|
||||
"security": [],
|
||||
"paths": {
|
||||
"/authorities": { "$ref": "#/components/pathItems/Authorities" },
|
||||
"/jurisdictions": { "$ref": "#/components/pathItems/Jurisdictions" },
|
||||
"/economic-activities": { "$ref": "#/components/pathItems/EconomicActivities" }
|
||||
},
|
||||
"components": {
|
||||
"pathItems": {
|
||||
"Authorities": {
|
||||
"get": {
|
||||
"summary": "Search the published authorities catalogue",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/version" },
|
||||
{ "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" },
|
||||
{ "name": "jurisdiction_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }
|
||||
],
|
||||
"responses": { "200": { "$ref": "#/components/responses/CatalogPage" }, "429": { "description": "Rate limit exceeded" } }
|
||||
}
|
||||
},
|
||||
"Jurisdictions": {
|
||||
"get": {
|
||||
"summary": "List territorial reference options for dependent dropdowns",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/version" },
|
||||
{ "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" },
|
||||
{ "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["country", "province", "district", "admin_post", "locality"] } },
|
||||
{ "name": "parent_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Required for district, admin_post and locality; the parent must be of the immediately preceding level." }
|
||||
],
|
||||
"responses": { "200": { "$ref": "#/components/responses/CatalogPage" }, "422": { "description": "Invalid or missing parent selection" }, "429": { "description": "Rate limit exceeded" } }
|
||||
}
|
||||
},
|
||||
"EconomicActivities": {
|
||||
"get": {
|
||||
"summary": "Search the portal-curated economic activity groupings",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/version" },
|
||||
{ "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" },
|
||||
{ "name": "parent_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Optional parent activity for hierarchical catalog browsing." },
|
||||
{ "name": "sector_id", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Optional sector filter for the dependent activity dropdown." }
|
||||
],
|
||||
"responses": { "200": { "$ref": "#/components/responses/CatalogPage" }, "429": { "description": "Rate limit exceeded" } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"parameters": {
|
||||
"q": { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } },
|
||||
"version": { "name": "version", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "A published immutable version; omitted selects the current effective version." },
|
||||
"page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
|
||||
"per_page": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }
|
||||
},
|
||||
"responses": {
|
||||
"CatalogPage": {
|
||||
"description": "Stable option values with Portuguese (Mozambique) labels. A not-yet-published catalogue returns an empty page and status not_published.",
|
||||
"headers": {
|
||||
"Cache-Control": { "schema": { "type": "string" } },
|
||||
"ETag": { "schema": { "type": "string" } }
|
||||
},
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["data", "links", "meta", "next_page_url", "prev_page_url", "current_page", "per_page", "total", "last_page"],
|
||||
"properties": {
|
||||
"data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEntry" } },
|
||||
"links": { "type": "object", "properties": { "next": { "type": ["string", "null"] }, "previous": { "type": ["string", "null"] } } },
|
||||
"next_page_url": { "type": ["string", "null"] },
|
||||
"prev_page_url": { "type": ["string", "null"] },
|
||||
"current_page": { "type": "integer" },
|
||||
"per_page": { "type": "integer" },
|
||||
"total": { "type": "integer" },
|
||||
"last_page": { "type": "integer" },
|
||||
"meta": { "$ref": "#/components/schemas/CatalogMetadata" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"CatalogEntry": {
|
||||
"type": "object",
|
||||
"required": ["id", "value", "code", "name", "label", "locale"],
|
||||
"properties": {
|
||||
"id": { "type": "string", "format": "uuid" },
|
||||
"value": { "type": "string", "description": "Stable API value; never the translated label." },
|
||||
"code": { "type": "string" },
|
||||
"name": { "type": "string" },
|
||||
"label": { "type": "string", "description": "Presentation label in pt-MZ." },
|
||||
"locale": { "const": "pt-MZ" },
|
||||
"parent_id": { "type": ["string", "null"], "format": "uuid" },
|
||||
"type": { "type": "string" },
|
||||
"version_no": { "type": "integer", "minimum": 1 },
|
||||
"sector_id": { "type": "integer" },
|
||||
"source_code": { "type": ["string", "null"] },
|
||||
"authority_type": { "type": "string" },
|
||||
"organization_id": { "type": "string", "format": "uuid" },
|
||||
"jurisdiction_id": { "type": ["string", "null"], "format": "uuid" },
|
||||
"jurisdiction_name": { "type": ["string", "null"] }
|
||||
}
|
||||
},
|
||||
"CatalogMetadata": {
|
||||
"type": "object",
|
||||
"required": ["catalog", "version", "locale", "current_page", "per_page", "total", "last_page"],
|
||||
"properties": {
|
||||
"catalog": { "type": "string", "enum": ["authorities", "jurisdictions", "economic-activities"] },
|
||||
"version": { "type": ["integer", "null"] },
|
||||
"locale": { "const": "pt-MZ" },
|
||||
"status": { "type": "string", "enum": ["not_published"] },
|
||||
"source_version": { "type": ["string", "null"] },
|
||||
"valid_from": { "type": ["string", "null"], "format": "date" },
|
||||
"valid_to": { "type": ["string", "null"], "format": "date" },
|
||||
"current_page": { "type": "integer" },
|
||||
"per_page": { "type": "integer" },
|
||||
"total": { "type": "integer" },
|
||||
"last_page": { "type": "integer" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user