open311 / swagger-open311 Goto Github PK
View Code? Open in Web Editor NEWAn swagger definition of Open311 GeoReport API
An swagger definition of Open311 GeoReport API
We need to check what parameters and returned fields are optional and how we can specify them? This affects esp.:
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:
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:
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:
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.:
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.
Swagger offers ways to formalize the input/output:
This includes esp. following sections
There are some parameters / fields repeated and might get unified. For example:
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
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.