Dear Neos Community and Neos Team,
tl;dr: our way towards a standardized Neos API; plus using neos/jsonschema for exposing validation rules of core DTOs
After this year’s Neos Conference, Bastian and myself revived our efforts about building an official Neos API (and later a CLI tool). So far we improved the tooling, and are working right now on the API.
We started exploring multiple ways, but finally settled on an OpenAPI compatible API now, as this is the most common denominator of current APIs right now. We then joined efforts with Daniel Kestler, because he also built a Neos API as part of Neos Studio - this gives us a real world API we can explore and improve, so this way we will be quite certain that all relevant use cases will be covered.
What we built so far
As we did not find any type-safe, code-first OpenAPI Generator in PHP, we built our own:
- GitHub - bwaidelich/neos-jsonschema: PHP Classes to represent JSON schema, see https://json-schema.org/ · GitHub - a base package containing only JSON Schema Definitions as PHP types, and a way how an object can declare its schema via implementing
ProvidesSchema::schema() - GitHub - bwaidelich/neos-schematic: Engine for coercion-capable schemas: describe PHP value objects (with attributes, or your own generation middleware), safely coerce unknown input into instances, and render to JSON Schema. · GitHub - a converter simple values to objects, and back; using the aforementioned JSON Schemata
- GitHub - bwaidelich/neos-openapi: Generate OpenAPI 3.1 specifications from attribute-annotated PHP methods, and serve them over PSR-7 · GitHub - an OpenAPI server using the lower layers.
This allows us to build APIs which are fully type-safe and complete, i.e. where we can guarantee that the published spec matches the implementation, including error conditions.
(Personal side-note: This fixes IMHO one of the most annoying pain points of the usual OpenAPI server generators - and it’s all simple Library packages; so this can be easily used outside Neos.)
These packages also solve composability; so it is possible to extend the existing API in a planned and well-defined manner.
Next Steps (short term)
- Move above packages to the Neos organization on Github (they already use the neos namespace but were created under Bastians account for the PoC phase)
- We’d like to adjust the Neos Core Value Objects to depend on neos-jsonschema, so that means that constraints like
a NodeAggregateId has a certain formatora DimensionValue has a given limitationwill be exposed using JSON Schema. - This means that the core will have a (small) dependency to neos/jsonschema. We do not want to introduce this lightly, but Bastian and myself think this would be worth doing for API consistency; and generally as best practice for type-safe code.
All other features do not need any Neos Core adjustments, but will happen in separate packages:
- We would like to have proper oAuth server support in the Neos Core, including support for fine-grained oAuth scopes - currently prototyping this via neos/oauth
- We’ll introduce neos/api (name TBD) which implements the core Neos API
- We’ll ask for a proper review once we are happy with the code quality of these packages
We’re also planning a budget proposal to push this topic forward more swiftly.
Next Steps (medium term)
After the core API is ready in v1, there are two branches forward:
- starting an official Neos CLI tool which interacts with this API.
- seeing how we can expose this functionality via MCP as well.
Please add feedback by answering here and/or adding some reaction emoji
Thanks and all the best,
Sebastian