sparkfabrik / nominatim-openapi Goto Github PK

Is your feature request related to a problem? Please describe.
Right now the official default format value for the /search endpoint is jsonv2 (see documentation) and the spec describes this response. But this discussion suggests that the best output format is geocodejson described by this spec.

Describe the solution you'd like
Change default format value of the OpenAPI spec to geocodejson and describe only this output in json schema. We should find or write the json schema for the geocodejson spec, but it is an extension of GeoJSON that already has an official json schema.

Describe alternatives you've considered
We can strictly follow the Nominatim documentation, but jsonv2 format has several well-known drawbacks and probably the next v2 of the api will drop it.

Additional context
Some useful resources:

• nominatim geocodejson output format
• geocodejson spec
• geojson schema
• json schema (see $ref and schema extension)

Describe the solution you'd like
The official documentation describes the /lookup endpoint. We should add it to paths section and describe all accepted parameters. The response schema (for the geocodejson format, see #2) will be the same of /search endpoint.

Additional context
Some useful resources:

• nominatim lookup endpoint
• paths object in openapi

Describe the solution you'd like
The official documentation describes the /status endpoint. We should add it to paths section and describe all accepted parameters. The default response schema should be json, described in json schema.

Warning! Status endpoint is not compliant with REST spec (returns always 200, also on errors).

Additional context
Some useful resources:

• nominatim status endpoint
• paths object in openapi
• json schema composition

Here I'm proposing final goals and a development roadmap for this project, discussion is open!

• OpenAPI specification following the official documentation: https://nominatim.org/release-docs/develop/ (please read also Nominatim/discussions/3115 and geocodejson-spec/issues/21 and #2)
• Some examples using code generators (ie. swagger codegen or api) and mapping libraries (ie. leaflet)
• A nodejs CLI (and npm package) using modern (ie. esm) and best practices
• A containerized version of playground

Describe your question or point of view about a topic
Security topic: how can the user be confident (and verify by himself!) that the published application is the same in the repository? Example: openapi specification as source code and as published resource. Two different URLs, same resource?

Describe the solution you'd like

The official documentation describes also the /details, /deletable, and /polygons endpoints. We should add it to paths section and describe all accepted parameters.

Describe alternatives you've considered

These endpoints are for debug or maintenance purposes and we can ignore them.

Additional context

Some useful resources:

• nominatim details endpoint
• nominatim deletable and polygons endpoints

Code of Conduct

• I agree to follow this project's Code of Conduct

Describe the solution you'd like

Swagger Editor can check the specs for syntax issues or invalid openapi yaml, but we need to test also endpoints and json schemas.

Is your feature request related to a problem?

Yes, at this moment we can't test errors in endpoints or json schemas and this should be mandatory for the first stable release.

Describe alternatives you've considered

Handmade checks using the playground.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Describe the solution you'd like
The official documentation describes the /reverse endpoint. We should add it to paths section and describe all accepted parameters. The response schema (for the geocodejson format, see #2) will be the same of /search endpoint.

Additional context
Some useful resources:

• nominatim reverse endpoint
• paths object in openapi