jeff-card
commented
5 years ago Thank you for your comment! A peer review was held on August 9th and we have the following feedback:
Error handling will be added to the “Design patterns” section. Some of the domain specific geospatial recommendations may be incorporated at a later date or subsequent versions and give reason to consider adding an appendices to this document. The content provided will be very useful at that time. Thank you.
mraross
Overall, a pretty good document. Handling version info in a header is brilliant.
Here are a few proposed additions:
Spatial considerations
Map projection
Use an srs parameter to define a map projection in the form of an EPSG code.
Support at least the following EPSG codes:
a. 4326 - Geographics (lat,lon in decimal degrees) b. 3005 - BC Albers c. 3857 - web mercator (mainly used for map tiles) d. 32607 - 32611 UTM north zones 7- 11
Use a default projection of 4326 (geographics).
Spatial Formats
Support geojson for point, line, polygon type geometries. Don't forgot to use the correct MIME type: application/vnd.geo+json
Support KML for point, line, polygon type geometries in XML. MIME type is: application/vnd.google-earth.kml+xml
Support GML for simple and complex feature schemas in XML. MIME type is: application/gml+xml
Use OGC WKT (well known text) for spatial data in columnar formats such as CSV and TSV.
Handling large amounts of data in a GET request
Your API may need to accept large amounts of parameter data in a GET request (e.g., a request for an optimal route involving 1,000 waypoints). In this case, it is acceptable to specify HTTP POST for this purpose even though server state remains unchanged.
Appropriate formats for large tabular results
When your API needs to return a very large amount of tabular data (e.g., thousands or millions of rows), consider using CSV or TSV formats.
Use lat/lon coordinates or OGC WKT (well known text) for spatial columns in these tabular formats such as CSV and TSV.
Error handling in appropriate formats
In addition to issuing the appropriate HTTP response codes, the format of additional error information should reflect the requested output format
a. A request for HTML or XHTML output should return error information in HTML format.
b. A request for KML output should return return error information in KML format.
c. A request for json, geojson, CSV, or TSV output should return an error in JSON format.
The Google json error object is useful for JSON error reporting. See:
https://google.github.io/styleguide/jsoncstyleguide.xml?showone=error#error
So, for example, a request for a non-existent siteID and json output will return an HTTP Response code of 404 and the following JSON error object:
{ "apiVersion": "3.4", "error": { "code": 404, "message": "Site Not Found", } }