Documentation for the /Road/{ids}/Disruption endpoint

Unified API
1

Hello

I’ve noticed a number of potential issues with the documentation for the /Road/{ids}/Disruption endpoint:

  1. There appears to be a mismatch between the output returned and the XML response schema. For example, when testing this endpoint against a road (e.g. A406), the response includes:
    “crs”: {
    “type”: “name”,
    “properties”: {
    “name”: “EPSG:4326”
    }
    }

However, these data elements are not in the XML response schema - can you check this please?

  1. A number of the data elements are missing descriptions - some of these are obvious, but it would be good to have descriptions provided for these:
    RoadDisruption: publishEndDate
    RoadDisruption: timeframe
    RoadDisruption: roadDisruptionLines
    RoadDisruption: roadDisruptionImpactAreas
    RoadDisruption: recurringSchedules
    DbGeography: geography
    RoadProject: projectId
    RoadProject: schemeName
    RoadProject: projectName
    RoadProject: projectDescription
    RoadProject: projectPageUrl
    RoadProject: consultationPageUrl
    RoadProject: consultationStartDate
    RoadProject: consultationEndDate
    RoadProject: constructionStartDate
    RoadProject: constructionEndDate
    RoadProject: boroughsBenefitted
    RoadProject: cycleSuperhighwayId
    RoadProject: phase
    RoadProject: contactName
    RoadProject: contactEmail
    RoadProject: projectSummaryPageUrl
    RoadProject: externalPageUrl
    RoadDisruptionLineL id
    RoadDisruptionLine: roadDisruptionId
    RoadDisruptionLine: isDiversion
    RoadDisruptionLine: multiLineString
    RoadDisruptionLine: startDate
    RoadDisruptionLine: endDate
    RoadDisruptionLine: startTime
    RoadDisruptionLine: endTime
    RoadDisruptionImpactArea: identifier
    RoadDisruptionImpactArea: roadDisruptionId
    RoadDisruptionImpactArea: polygon
    RoadDisruptionImpactArea: startDate
    RoadDisruptionImpactArea: endDate
    RoadDisruptionImpactArea: startTime
    RoadDisruptionImpactArea: endTime
    RoadDisruptionSchedule: startTime
    RoadDisruptionSchedule: endTime
    DbGeographyWellKnownValue: coordinateSystemId
    DbGeographyWellKnownValue: wellKnownTest
    DbGeographyWellKnownValue: wellKnownBinary

  2. As well as descriptions, would it be possible to know the lengths of these data elements and whether all of them are optional or if some are mandatory?

2

Hi @Waseem, where are you getting the XML schema from? If I go to the Swagger documentation and click on response schema, I see at least a name and data type for every element in the response.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Road/Road_Disruption

3

Hi,

I’m having the same problem.

The documentation states that the geometry properties (for instance, the geography property of RoadDisruption) have this structure:

"geography": {
    "geography": {
        "coordinateSystemId": 0,
        "wellKnownText": "string",
        "wellKnownBinary": "string"
      }
},

But when calling the api I’m getting

"geography": {
      "type": "Point",
      "coordinates": [
        -0.129855,
        51.563959
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
},

I generated all my java models using the swagger specification (https://api.tfl.gov.uk/swagger/docs/v1) and it’s failing to deserialise these properties.

4

Hi @fcovas I think what’s happening here is that for JSON we override the serialisation of DbGeography to be GeoJSON. This is mentioned in the documentation::

This is not being picked up in the Swagger spec (because Swashbuckle doesn’t detect our override when it generates the Swagger file). I’ll create a ticket to try and find a fix for that SVC-4636. In the meantime I’m afraid you might have to override your generated Java types so that they match our response.

5

@Tim

I figured something like that was happening, I was just expecting the entities generated by the swagger file to have that into account. I made a workaround and made a custom deserialisation for DbGeography.

Just one note about the geojson. According to the latest specification (RFC 7946: The GeoJSON Format), the crs field is no longer included. By default all the geometries are in WGS84. See sections “4. Coordinate Reference System” and “B.1. Normative Changes”. Trying to decode the geojson returned by the api is failing in some libs because of this.

I’m looking forward for the fix. Thanks.

6

Thanks @fcovas I’ll create a task to get the CRS field removed SVC-4650