open311 / swagger-open311 Goto Github PK

We need to check what parameters and returned fields are optional and how we can specify them? This affects esp.:

• request.status_notes
• request.agency_responsible
• request.adress_id
• ...

ron AD swagger.io is waiting for a mail, if we get finished with the swagger specs 😀

I would appreciate any help and esp. an review / compare / ... of this swagger definiton vs. the currently official open311 standard.

We need to check:

• Are URLs ok?
• Are (required / optional) parameters ok?
• Are results (in JSON and XML) ok?
• ...

the field request.zipcode is explicitly defined but informal also mentioned at the request.adress field:

This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code .

Makes it sense to remove this additional field or do we want to add more structured adress fields?

Corresponding to swagger, we need to pick a license for the API: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#licenseObject

I didn't found a hint on how we license Open311 and I'm not sure if this refers to the YAML definitions or also to the generated class stubs or even the data gathered with the API? 😕

How can we check our YAML specs against existing solutions (that represent the old specs) and vice versa?

This is an special (complex) case of #7 and #8 At the current doc we say:

A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.

So we might need to discuss and define:

• supported filetypes/content of the URLs (images, video, ...)
• supported URLs(flickr, facebook, ...)
• supported services and procedures to get content (e.g. Open Graph , oEmbed, crawler, ...)

Our current spec say that JSON is optional and need to be checked via service discovery.

How can underline this problem and make it somewhat formal/machine readabe?

Think about an server offering the API for a period of time. During the months/years it's getting obvious, that the configuration/scenario of the operator will change and he needs to add or change e.g. service definitions, service name or codes.

Are there any speficications how we expect that the API will deal with that?
Do we suggest to present data as "snapshots" (keep values as the were while editing the data) or do we expect to present consistent data as 'live view' ?
What we suggest about migration and backwards compability of data?

A technical doc is usual as short as possible while staying exact and accurate, So we might do some polishing at the end to avoid unessary texts and make the specification easy to read.

We might outsource and refer the error codes as a more general concept: (search 'error_model')https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject

We have some parameters / fields that are present or (exclusive) other fields are present. For example:

• request.id | token
• atlon|adress
• ...

I have no idea how we can model this logic 😕

If we want to get good formal definitions (see #7 ) we might also bring some more logic into datastructures, so validation might be easier. This includes esp.:

• attribute.code
• attribute.order
• service.id
• address
• ...

This might also result in discussions (e.g. do we consider IDs always to be strings (e.g. hashes, hex numbers, ...) or just positive integers, ...)?

Summary
The spec is internally inconsistent in what JSON type it uses in its service_code and service_request_id examples. These examples don't match the type: string definition for this swagger spec.

Proposed solution: change them all to string types or change them all to integer types and clearly state the type in the spec.

TL;DR
The swagger spec specifies service_request_id and service_code as

service_code:
  type: string
  format: uid
service_request_id:
  type: string
  format: uid

Which would imply the following formats:

JSON

"service_request_id": "1335131"
"service_code": "124"

XML

<service_request_id>1335131</service_request_id>
<service_code>124</service_code>

The XML can be interpreted as either a string or an integer. Note that the spec (http://wiki.open311.org/GeoReport_v2/) defines it in its sample JSON in both ways.

Get Service List: "service_code":001
Get Service Definition: "service_code":"DMV66"

For service_request_id it is only specified in the json integer format "service_request_id":293944 this would imply that the service_request_id field is actually an Integer and not a string.

cc @zdicesare @philipashlock

Swagger offers ways to formalize the input/output:

• https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#dataTypeFormat
• https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject

This includes esp. following sections

• service.type
• attribute.datatype
• request.requested_datetime
• ...

There are some parameters / fields repeated and might get unified. For example:

• service_name
• service_code
• jurisdiction_id
• ...

Would be good for mocking and verification, but maybe this turns out to be complex?

There are some calls that confused me during modelling the spec, as (to me) it seems strange that they seem to realize an array / 1:n relation

• POST Service Request
• GET service_request_id from a token
• GET Service Request

Swagger allows to embedd example request payloads: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#exampleObject

Our spec contains raw JSON/XML examples, so do we want to add them? Does this make sense to mock/simulate the API for clients/servers? https://www.npmjs.com/package/swagger-server

Swagger supports general API security concepts: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject

We need to implement api_key authorization and error codes. Our spec also uses only https, so we might require https schema?