First draft of OGC API Routes implementation

[skyNacho]

OGC API Routes is still on draft status but I think it is time to commit and start a discussion on the way this was implemented.

Routing uses pgRouting as the default routing engine, but allowing for additional engines to be integrated. Routing is implemented as a process, able to use both API Processes or API Routes, as the standard allows for both.

There are several drawbacks when using API Processes, in particular that the current code structure does not allow to call the process with a process-id/route_id parameter (required to generate the links in the Route Exchange Model) or that the error codes are generic and not very useful. When using Routes API these limitations are solved by implementing them in api.py. I would like to discuss options to fix the limitations for API Processes.

Conformance is a bit different in API Routes than in other OGC APIs, adding the concept of Properties. The code in api.py has been adapted as well as the corresponding template. The reason for these properties in the conformance declaration is due to two parameters (preferences and modes) that can have the values defined by the service provider (in the example, these are fastest and shortest for preferences and only vehicle for modes, but each provider can define their own). Eventually, additional parameters can be defined that follow this requirement.

Generated routes and their definitions are stored in Route Exchange Model and Geojson respectively in a directory path configurable in pygeoapi-config.yml.

The configuration of pgRouting is similar to setting up a postgreSQL provider. I added an additional parameter, search_buffer, that helps limiting the search for the requested waypoints in the dataset, as well as optimizing the pgRouting route computation.

If this API is approved and included in pygeoapi, documentation must be updated. A decision needs to be made about how much of pgRouting setup is included in pygeoapi documentation.

[skyNacho]

I have fixed the minor issues. Next week I will do the following:

• Move CRUD processes to the plugin code
• Review sql queries and implement db variable binding
• Update Starlette implementation
• Discuss on the response status codes

I'll leave tests and doc for later iterations.

Your point on reusing code for OAFeat Part 4 is valid, as the transactional capabilities for Routes has been specifically designed to be similar to Features Part 4 in many aspects.

[skyNacho]

I think I have fixed all the raised issues. The only topic I could not complete was on the error handling when executing a process, as it seems like the manager is already handling the errors. I should research a bit more on that topic.

Apart from that, it is ready for a new review.

[skyNacho]

I eventually only modified the code in dummy process manager, which is the one used by default. It is inheriting from base but overwriting the execute_process function (with all the error handling). I do not think the code in base process manager execute_process function is used at all.

Anyway, I am now happy with the code. I will now start working on the tests part. Any hints will be welcome.

[skyNacho]

A new conversation started a few weeks ago in the OGC Routes SWG with some interesting suggestions that include substantial changes in the API and container definitions. Some of these suggestions have already been approved and others are still in discussion.

Current implementation in pygeoapi needs to be adapted. I will wait until we have a stable draft again before adding the new changes.

[tomkralidis]

@skyNacho not sure the current status on this. Are you able to update/rebase, or should we close/defer?

[skyNacho]

Hi Tom, I am still waiting for the standard to get finalized. I don't want to do the effort of implementing the module and see again how the standard changes. There are still a bunch of issues to discuss and decide, so I do not think it will be approved in the short term. You can see the list of pending issues here: https://github.com/opengeospatial/ogcapi-routes/issues/70

I will retake the efforts once the standard is on its way to approval. For the moment I would close or even reject this pull request in order to avoid noise.

[tomkralidis]

Hi @skyNacho: how about the following:

• close this PR, but keep the branch
• add an issue to pygeoapi,

The idea is that the feature/enhancement stays in our issue queue, and you can issue a new or updated referring to the issue per se. Does this work for you?

[skyNacho]

Yes, that makes sense, thanks