Endpoint Styles: Simplification & Minimalization

[jacob-a-brown]

Rather than have a number of different endpoints that essentially serve the same data (for GET requests), it may be simpler to implement a single endpoint that can return that data in a variety of different formats. This will make it easier to understand the API because a user won't have to go to different endpoints to obtain the same data (though in different formats). Other services, like Geoconnex and USGS' water data services, have this implemented and are good proofs of concept.

Why is this easier for the user?

The same query can be reused to obtain the same data, but in different formats (such as ?format=geojson or ?format=shapefile).

Why is this easier for the developer?

The same logic can be used to obtain the same data, and then at the end of the endpoint function a series of if/else statements can be used to serve the data in the desired format.

e.g.

def get_locations(...) -> ResponseType1 | ResponseType2 | ResponseType3 | ...:
    <code to get locations>

    if format == 'feature_collection':
        return <feature collection>
    elif format == 'shapefile`:
        return <shapefile>
    elif format == 'geojson':
        return <geojson>
    elif format == 'xml':
        return <xml>
    else:
        return <dict>

Challenges

• Can we create repeatable functions for the return types?
• The OpenAPI documentation will have to be a bit more bespoke since a number of different viable responses will be available.

Thoughts?

[jacob-a-brown]

This isn't just applicable to locations & things, but can also be used for observation endpoints, like ?format=crosstab or ?format=csv or ?format=dict.

[jacob-a-brown]

A disadvantage could be that the user expects the same endpoint to always return data in the same format, so by allowing them to specify and change the format they may make mistakes or have mistaken assumptions.

[jirhiker]

I agree. Mimicking good parts of other services is always a good idea. See PR 39