Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

The view from DataBC Location Services

Open
  • Is something wrong?
#11 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Domain
api, documentation

Research direction

No file, test, or entry point is named; start by locating the API guideline document covered by this issue and compare its current sections with the proposed spatial, large-request, tabular-format, and error-handling additions. Done would require an agreed scope and updated guidance, but the issue does not define which proposals are accepted or how they should be integrated.

Written by the indexing model from the issue text.

Description

feedback

Overall, a pretty good document. Handling version info in a header is brilliant.

Here are a few proposed additions:

Spatial considerations

Map projection

  1. Use an srs parameter to define a map projection in the form of an EPSG code.

  2. 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

  3. Use a default projection of 4326 (geographics).

Spatial Formats

  1. Support geojson for point, line, polygon type geometries. Don't forgot to use the correct MIME type:
    application/vnd.geo+json

  2. Support KML for point, line, polygon type geometries in XML. MIME type is:
    application/vnd.google-earth.kml+xml

  3. Support GML for simple and complex feature schemas in XML. MIME type is:
    application/gml+xml

  4. 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

  1. 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.

  2. 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

  1. 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.

  2. 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",
}
}​

Dominant language
No language data
Stars
34
Forks
10
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from bcgov/api-guidelines

All issues in bcgov/api-guidelines

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.