[simahawk]

Motivation

base_rest ties every API to its components and to the restapi route type, so an API can't leave base_rest (shopfloor included) without a replacement. This module provides the common plumbing of an API endpoint as a route type of its own, http_json, independent of components. APIs can then move to it one endpoint at a time. The error format and the params stay compatible with base_rest .

Key features

• http_json route type: params parsed once from the query string and the body (JSON or forms)
• language set from the Accept-Language header
• input and output validated/converted by pluggable params declared on the route (see http_json_cerberus)
• results serialized as JSON (dates as ISO strings, decimals as floats)
• exceptions turned into JSON error responses w/ the proper status codes
• hooks on each step, extensible via standard Odoo inheritance

A bit more of context in comparison to base_rest/fastapi (from module's readme)

base_rest (OCA/rest-framework) has been the foundation of many APIs,
including the Shopfloor apps. Over time it showed some limits:

• it is a monolith: dispatcher, service layer, validation,
  documentation and routing are bound together
  and you cannot use one piece without the others
• services must be components, a second registry
  with its own inheritance and boot lifecycle,
  which is often used only to look up a class by name
• controllers are generated at boot from the services,
  making routing hard to follow and to customize

The fastapi stack is a way to go for new standalone APIs,
but moving existing APIs to it means rewriting every service and schema and endpoints are not extendable models.
Plus, it pulls in more external dependencies that for many cases are not needed.

This module is the base of a lighter stack, made of small modules
that can be used separately and extended via standard Odoo inheritance:

• http_json_dispatcher: the http_json route type (parsing, validation hooks, JSON errors)
  usable by plain Odoo controllers
• endpoint_spec: declare endpoints on services, for routes generators
• http_json_cerberus: Cerberus validation
• openapi_doc_base: API docs from the actual routes
• endpoint_route_handler generators: routes computed from the code
  without storing a row per route

Goals:

• simplify the base_rest stack without moving to fastapi
• keep modules small and reusable
• drop the dependency on component, staying highly customizable
  (routing keys per route, ir.http hooks per database)
• stay compatible with base_rest clients (error format, validation behavior)
  to allow a gradual migration

The only doubt that I have ATM is: should this stay here or go to rest-framework repo? (even though is not strictly bound to "REST" stuff.

@lmignon would be nice to have your feedback 🙏
One last thing: as this work it's a derivation of base_rest, I've tried to keep the copyright where it made sense, but please let me know if I left something behind 😉

[lmignon]

@simahawk I like the idea and the approach. It seems like a good step towards reducing the amount of code while adding more value on top of Odoo's standard features while also providing a safe path away from base_rest.

Regarding:

fastapi endpoints are not extendable models.

I agree, but even though Odoo controllers can be inherited, if the business logic is implemented directly in a route method, it becomes difficult to extend as well. That's why, regardless of the approach, the actual logic should be delegated to a model, wizard, or transient model. 😏

For the record, pydantic models are extendable.... (you need extra libs and addon but it works like a charm)

rest-framework seems to me like a more logical place for this kind of addon, but that's just my personal opinion.

[lmignon]

@simahawk http_json is may be too restrictive.... REST doesn't limit to json. You could receive multipart request with a form part with a json document and others part with binary files....
Another question: how do you plan to allow the developer to not hard link its service to a specific authentication method?

[simahawk]

@simahawk http_json is may be too restrictive.... REST doesn't limit to json. You could receive multipart request with a form part with a json document and others part with binary files....

That's correct but I couldn't find a better naming and a json payload is what is going to handle 99% of the times 😅 Would you prefer http_api?

Another question: how do you plan to allow the developer to not hard link its service to a specific authentication method?

One of the nice pros of this approach is that you can use standard controllers and as such you can use auth="whatever" and support that w/ ir.http._auth_method_whatever().

Same for the Cerberus validator #182 that you can use on std controllers.

[lmignon]

That's correct but I couldn't find a better naming and a json payload is what is going to handle 99% of the times 😅 Would you prefer http_api?

http_api looks better to me, but this choice deserves more input than just mine. ;-)

[simahawk]

That's correct but I couldn't find a better naming and a json payload is what is going to handle 99% of the times 😅 Would you prefer http_api?

http_api looks better to me, but this choice deserves more input than just mine. ;-)

Curious thing: I first chose that name but I found it too generic 😆

[simahawk]

renamed module back to http_api* and routing type to http_api