From 3fff7ce556d78dcf27b76bffc7f29d44d6c9a542 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 01/10] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From f6add174b61f888754e395c1df96476597ed3f37 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 02/10] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From aa6cb7f4ece7a9ca82aea5998c9f960c89e3dc97 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 03/10] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 3cfa5a8bf44528d51b3146bd4aff6569052d8437 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 04/10] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 979d0c81f57351585486a572ad8bf62311952d44 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Wed, 29 May 2024 16:38:42 +0200 Subject: [PATCH 05/10] Aligning spec to current behaviour --- service-alerts-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..dcab320 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -83,7 +83,7 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alertId}.json: + /alerts/{alertId}.json: get: tags: - "v1" From fbd047d33d3b806f5c868baac3a69c85f3194746 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 06/10] DRYing out the current spec --- service-alerts-api.yaml | 214 +++++++++------------------------------- 1 file changed, 47 insertions(+), 167 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 175e99b..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -19,153 +19,18 @@ tags: description: "Second version of API with AI-generated social media post fields" paths: - /coct-service_alerts-current-unplanned.json: + /coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v0" deprecated: true - summary: Current unplanned outages - description: Get all currently active unplanned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-current-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Current planned outages - description: Get all currently active planned service outages - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-7days-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-unplanned.json: - get: - tags: - - "v0" - deprecated: true - summary: All unplanned outages - description: Get all unplanned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /coct-service_alerts-all-planned.json: - get: - tags: - - "v0" - deprecated: true - summary: All planned outages - description: Get all planned service outages going back several years - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-current-unplanned.json: - get: - tags: - - "v1" - summary: Current unplanned outages - description: Get all currently active unplanned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-current-planned.json: - get: - tags: - - "v1" - summary: Current planned outages - description: Get all currently active planned service outages with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-unplanned.json: - get: - tags: - - "v1" - summary: Unplanned outages for Last 7 Days - description: Get all unplanned service outages active over the last 7 days with social media fields - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-7days-planned.json: - get: - tags: - - "v1" - summary: Planned Outages for Last 7 Days - description: Get all planned service outages active in the last 7 days with social media fields + summary: List service alerts + description: Get all service alerts, according to the parameters set. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -175,27 +40,19 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV0' - /v1/coct-service_alerts-all-unplanned.json: - get: - tags: - - "v1" - summary: All unplanned outages - description: Get all unplanned service outages going back several years with social media fields. - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' - /v1/coct-service_alerts-all-planned.json: + /v1/coct-service_alerts-{timeFrame}-{planned}.json: get: tags: - "v1" summary: All planned outages description: Get all planned service outages going back several years with social media fields. + deprecated: true + description: Get all service alerts, according to the parameters set with additional social media fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned responses: '200': description: Successful response @@ -206,18 +63,15 @@ paths: items: $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alert_id}.json: + /v1/alerts/{alertId}.json: get: tags: - "v1" summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: - - name: alert_id - in: path - description: ID of the service alert to retrieve - required: true - schema: - type: integer + - name: alertId + $ref: '#/components/parameters/alertId' responses: '200': description: Successful response @@ -226,6 +80,32 @@ paths: schema: $ref: '#/components/schemas/ServiceAlertV1' components: + parameters: + timeFrame: + in: path + description: Time frame from which select service alerts will be listed. + schema: + type: string + enum: + - current + - 7days + - all + required: true + planned: + in: path + description: Whether this potential outage was a result of planned maintenance or not. + schema: + type: string + enum: + - planned + - unplanned + required: true + alertId: + in: path + description: ID of the service alert to retrieve + required: true + schema: + type: integer schemas: ServiceAlertV0: type: object @@ -321,9 +201,9 @@ components: properties: tweet_text: type: string - description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B LLM. + description: 280 character or less summary of the service alert, formatted with social media in mind. Generated using wizardlm-13B or Llama3-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected water outage due to burst pipe. For assistance, use request number 9116664427 when contacting the City." toot_text: type: string - description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B LLM. + description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 97247686f37d16bb44d737228c3d1a48d77a23aa Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 07/10] Adding v1.1 spec to API path --- docs/area_type_lookup.md | 8 +++++ service-alerts-api.yaml | 67 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 5 deletions(-) create mode 100644 docs/area_type_lookup.md diff --git a/docs/area_type_lookup.md b/docs/area_type_lookup.md new file mode 100644 index 0000000..1191618 --- /dev/null +++ b/docs/area_type_lookup.md @@ -0,0 +1,8 @@ +# Area Type Lookup + +This document describes the links between specific `area_type` values, and GIS datasets on the City of Cape Town's Open +Data Portal. + +| Area Type Value | Layer URL | Area Lookup Column | +|----------------------------|-------------------------------------------------------------------------------------|--------------------| +| `Official Planning Suburb` | https://odp-cctegis.opendata.arcgis.com/datasets/cctegis::official-planning-suburbs | `OFC_SBRB_NAME` | \ No newline at end of file diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 43d74edb9197158c7a353911e0eefb78db7b3ea0 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:10:48 +0200 Subject: [PATCH 08/10] DRYing out the current spec --- service-alerts-api.yaml | 67 +++-------------------------------------- 1 file changed, 5 insertions(+), 62 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..34f7754 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.1.0 + version: 1.0.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,8 +17,6 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" - - name: "v1.1" - description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -46,8 +44,9 @@ paths: get: tags: - "v1" + summary: All planned outages + description: Get all planned service outages going back several years with social media fields. deprecated: true - summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -63,31 +62,11 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1.1/service-alerts/{timeFrame}/{planned}: - get: - tags: - - "v1.1" - summary: list service alerts - description: Get all service alerts, according to the parameters set with additional geospatial fields. - parameters: - - $ref: '#/components/parameters/timeFrame' - name: timeFrame - - $ref: '#/components/parameters/planned' - name: planned - responses: - '200': - description: Successful response - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ServiceAlertV1' + /v1/alerts/{alert_id}.json: /v1/alerts/{alertId}.json: get: tags: - "v1" - deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -100,22 +79,6 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' - /v1.1/service-alert/{alert_id}: - get: - tags: - - "v1.1" - summary: Get a specific service alert by ID - description: Retrieve detailed information about a service alert by its unique ID - parameters: - - name: alertId - $ref: '#/components/parameters/alertId' - responses: - '200': - description: Successful response - content: - application/json: - schema: - $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -243,24 +206,4 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" - - ServiceAlertV1.1: - allOf: - - $ref: '#/components/schemas/ServiceAlertV1' - - type: object - properties: - area_type: - type: string - nullable: true - description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. - example: "Official Planning Suburb" - enum: - - Official Planning Suburb - - Solid Waste Regional Service Area - - Citywide - - Driving Licence Testing Centre - geospatial_footprint: - type: string - description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. - example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file From 2eb6a518aa276f57bd294fcde33f984c8a401b95 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Tue, 30 Apr 2024 23:17:20 +0200 Subject: [PATCH 09/10] Adding v1.1 spec to API path --- service-alerts-api.yaml | 67 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index 34f7754..dea30bc 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Service Alerts API description: Data API for service outage alerts. Hosted in the cloud, behind a CDN, so feel free to query as frequently as required. - version: 1.0.0 + version: 1.1.0 contact: name: Gordon Inggs email: gordon.inggs@capetown.gov.za @@ -17,6 +17,8 @@ tags: description: "Initial version of API" - name: "v1" description: "Second version of API with AI-generated social media post fields" + - name: "v1.1" + description: "Minor increment of second version of API. Mostly adds geospatial related fields." paths: /coct-service_alerts-{timeFrame}-{planned}.json: @@ -44,9 +46,8 @@ paths: get: tags: - "v1" - summary: All planned outages - description: Get all planned service outages going back several years with social media fields. deprecated: true + summary: list service alerts description: Get all service alerts, according to the parameters set with additional social media fields. parameters: - $ref: '#/components/parameters/timeFrame' @@ -62,11 +63,31 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alert_id}.json: + /v1.1/service-alerts/{timeFrame}/{planned}: + get: + tags: + - "v1.1" + summary: list service alerts + description: Get all service alerts, according to the parameters set with additional geospatial fields. + parameters: + - $ref: '#/components/parameters/timeFrame' + name: timeFrame + - $ref: '#/components/parameters/planned' + name: planned + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceAlertV1' /v1/alerts/{alertId}.json: get: tags: - "v1" + deprecated: true summary: Get a specific service alert by ID description: Retrieve detailed information about a service alert by its unique ID parameters: @@ -79,6 +100,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ServiceAlertV1' + /v1.1/service-alert/{alert_id}: + get: + tags: + - "v1.1" + summary: Get a specific service alert by ID + description: Retrieve detailed information about a service alert by its unique ID + parameters: + - name: alertId + $ref: '#/components/parameters/alertId' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceAlertV1.1' components: parameters: timeFrame: @@ -206,4 +243,24 @@ components: toot_text: type: string description: 300 character or less summary of the service alert, formatted with social media in mind. Includes hashtags for the sake of indexing. Generated using wizardlm-13B or Llama-8B LLM. - example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" \ No newline at end of file + example: " šŸš§Burst PipešŸš§\nšŸ“Pinoak Avenue, Vredehoek\nā°Feb 14, 6:35 PM - Feb 15, 12:35 AM\nUnexpected burst water issue. For assistance, contact City with request number 9116664427\n#CapeTown #Water&Sanitation" + + ServiceAlertV1.1: + allOf: + - $ref: '#/components/schemas/ServiceAlertV1' + - type: object + properties: + area_type: + type: string + nullable: true + description: Type of geographic area described by area field. In some instances, this value indicates a GIS dataset on the City's Open Data Portal that can be used to look up the geospatial area described. + example: "Official Planning Suburb" + enum: + - Official Planning Suburb + - Solid Waste Regional Service Area + - Citywide + - Driving Licence Testing Centre + geospatial_footprint: + type: string + description: Best effort geospatial location of the issue, based upon the contents of the area_type, area and location fields. Provided in Well-Known Text (WKT), ISO/IEC 13249-3:2016 compliant format, using the EPSG 4326 CRS. + example: "POLYGON ((18.550986 -33.866492, 18.550989 -33.866483, 18.550993 -33.866475, 18.550997 -33.866467, 18.551003 -33.866459, 18.551008 -33.866452, 18.551015 -33.866445, 18.551022 -33.866439, 18.551187 -33.866313, 18.551231 -33.866280, 18.551239 -33.866275, 18.551248 -33.866270, 18.551257 -33.866266, 18.551266 -33.866263, 18.551276 -33.866261, 18.551285 -33.866260, 18.551295 -33.866260, 18.551305 -33.866261, 18.551315 -33.866262, 18.551324 -33.866265, 18.551333 -33.866269, 18.551342 -33.866273, 18.551350 -33.866279, 18.551358 -33.866285, 18.551365 -33.866292, 18.551371 -33.866299, 18.551377 -33.866307, 18.551382 -33.866316, 18.551385 -33.866325, 18.551388 -33.866334, 18.551390 -33.866344, 18.551392 -33.866353, 18.551392 -33.866363, 18.551391 -33.866373, 18.551389 -33.866383, 18.551386 -33.866392, 18.551383 -33.866401, 18.551378 -33.866410, 18.551373 -33.866418, 18.551367 -33.866426, 18.551360 -33.866433, 18.551352 -33.866439, 18.551309 -33.866473, 18.551170 -33.866578, 18.551152 -33.866642, 18.551149 -33.866651, 18.551145 -33.866660, 18.551141 -33.866669, 18.551135 -33.866677, 18.551129 -33.866684, 18.551121 -33.866691, 18.551114 -33.866697, 18.551105 -33.866702, 18.551097 -33.866707, 18.551088 -33.866710, 18.551078 -33.866713, 18.551068 -33.866715, 18.551059 -33.866715, 18.551049 -33.866715, 18.551039 -33.866714, 18.551030 -33.866712, 18.551020 -33.866709, 18.551011 -33.866705, 18.551003 -33.866700, 18.550995 -33.866694, 18.550987 -33.866688, 18.550980 -33.866681, 18.550974 -33.866673, 18.550969 -33.866665, 18.550965 -33.866656, 18.550961 -33.866647, 18.550959 -33.866637, 18.550957 -33.866628, 18.550956 -33.866618, 18.550956 -33.866608, 18.550958 -33.866598, 18.550960 -33.866589, 18.550986 -33.866492))" \ No newline at end of file From 5b0ce9f139fdbf8fad49725e850b73d819b807f2 Mon Sep 17 00:00:00 2001 From: Gordon Inggs Date: Wed, 29 May 2024 16:38:42 +0200 Subject: [PATCH 10/10] Aligning spec to current behaviour --- service-alerts-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service-alerts-api.yaml b/service-alerts-api.yaml index dea30bc..dcab320 100644 --- a/service-alerts-api.yaml +++ b/service-alerts-api.yaml @@ -83,7 +83,7 @@ paths: type: array items: $ref: '#/components/schemas/ServiceAlertV1' - /v1/alerts/{alertId}.json: + /alerts/{alertId}.json: get: tags: - "v1"