Work Package #45088

Improved REST support

Added by Bastian Waidelich over 2 years ago. Updated over 1 year ago.

Status:Resolved Start date:2011-05-29
Priority:Should have Due date:2013-04-13
Assigned To:Bastian Waidelich % Done:

100%
Category:General / Project Spent time: 108.00 hours
Target version:1.0 beta 1 Estimated time:108.00 hours

Description

Improved REST support

Motivation

A solid webservice interface provides countless possibilities. With a proper foundation it would easily be possible to expose the TYPO3 Content Repository as service for instance. This would allow other systems to interact with arbitrary nodes (e.g. mobile clients creating pages, a simple plugin creating content nodes, ...).
Another use case are custom service APIs for the clients business logic. Flow already provides basic support for that, but there are some important parts missing.

Goal

The goal is to have a solid foundation to easily provide custom REST APIs. What has been started at #37604 will be used as base for this.

Deliverables

  • MUST: more flexible request handling
    • Reworked argument merging #45290 - this is required in order to fix argument mapping with non-GET requests
    • More flexible parsing of body arguments #45293 - this is required in order to support custom request formats
  • MUST: Routing improvements
    • Global route constraints #27117 - this is required in order to match requests based on the request method and/or arbitrary request headers
    • Nested sub routes #43966 - this is required in order to allow developers to easily include "RESTful" routes
  • MUST: session-less authentication #45282 - currently Flow creates a session for every authentication, this is incompatible with REST
  • MUST: solid test coverage
  • MUST: documentation
  • COULD: improved error handling #43569 - currently exceptions are rendered independently from the requested format (HTML for all web requests)
  • COULD: exemplary (mobile) client that interacts with the TYPO3CR

typo3neos-distribution-base-45088.pdf (5.3 kB) Sebastian Kurfuerst, 2013-02-16 15:11

Subtasks

Feature #45282: Support for "sessionless authentication"ResolvedBastian Waidelich

Feature #43966: Allow all routes to include sub routesResolvedBastian Waidelich

Feature #27117: Bind routes to HTTP request methodsResolvedBastian Waidelich

Feature #45293: More flexible parsing of body argumentsResolvedBastian Waidelich

Bug #45290: Body arguments should not be merged before property mappi...ClosedBastian Waidelich

Related issues

related to TYPO3.Flow - Feature #37604: Make Flow RestController useless by improving MVC stack Resolved 2012-05-30
related to Base Distribution - Story #44913: RESTful NodeController for easy comment creation On Hold
related to TYPO3.Flow - Feature #43569: Exception Handler should respect format Closed 2012-12-04 2013-04-13

History

#1 Updated by Andreas Förthner over 2 years ago

Just a short commet regarding the session-less authentication: This is already possible as long as none of your configured authentication providers starts a session (@Flow\Session(autoStart=true) at the authenticate() method). We simply need a provider without this annotation and no session should be started/needed.

#2 Updated by Bastian Waidelich over 2 years ago

Andreas Förthner wrote:

Just a short commet regarding the session-less authentication: This is already possible as long as none of your configured authentication providers starts a session [...]

I don't think so, I already found 3 places where Flow relies on a session to be active ("AuthenticationProviderManager::emitAuthenticatedToken()", "AuthenticationProviderManager::isAuthenticated()" and "RequestDispatchingAspect::setInterceptedRequest()"). For the latter Christopher already came up with a solution: https://review.typo3.org/#/c/17967/

#3 Updated by Bastian Waidelich over 2 years ago

  • Subject changed from [WIP] Improved REST support to Improved REST support

#4 Updated by Sebastian Kurfuerst over 2 years ago

Discussion during EAB / Neos meeting:

  • Bastian estimates that 25% of this whole package is documentation.
  • the documentation also should include easy-to-run examples (f.e. how to create pages using the REST API); f.e. with curl or guzzle
  • proper REST support would also be the basis for implementing e.g. CMIS standard lateron

#5 Updated by Sebastian Kurfuerst over 2 years ago

  • Status changed from New to Accepted

#6 Updated by Sebastian Kurfuerst over 2 years ago

  • Due date set to 2013-03-29
  • Start date changed from 2013-01-31 to 2013-02-16
  • Estimated time set to 108.00

Has been discussed with Jan-Hendrik from the EAB on 12.02.2013; and has been accepted on 15.02.2013 by the EAB.
(The attached PDF is a snapshot of this work package at the time of acceptance.)

So, Bastian and Andi, you can schedule this work package in your day-to-day calendar and implement it then -- can't wait to see it in Neos 1.0 :-)

Another side-note: Please do not forget to add comments to this work package and update "% done" while you are working on this package.

Greets, Sebastian

#8 Updated by Bastian Waidelich over 2 years ago

  • % Done changed from 0 to 10

Status update: "sessionless authentication" is under review: #45282

#9 Updated by Bastian Waidelich over 2 years ago

Status update: "Nested sub routes" is under review: #43966

#10 Updated by Aske Ertmann over 2 years ago

  • Estimated time set to 108.00

#11 Updated by Aske Ertmann over 2 years ago

Would it make sense to set the due date to the end of week 14?

#12 Updated by Bastian Waidelich over 2 years ago

Aske Ertmann wrote:

Would it make sense to set the due date to the end of week 14?

Mh, that seems not to be possible with "child tickets"!?

#13 Updated by Bastian Waidelich over 2 years ago

Bastian Waidelich wrote:

Would it make sense to set the due date to the end of week 14?

Mh, that seems not to be possible with "child tickets"!?

It seems, it is in fact – by setting the due date of all open sub tasks

#14 Updated by Bastian Waidelich over 2 years ago

FYI: The date selector of forge shows the wrong week number, I therefore expected the deadline by the end of next week (and set the due date accordingly)

#15 Updated by Bastian Waidelich about 2 years ago

Status update: I have some local prototypes for the remaining two issues (#45293 and #45290) but they still need to be discussed with the team as they probably contain breaking changes. I'll update the status again after the Code Sprint

#16 Updated by Sebastian Kurfuerst about 2 years ago

  • Subject changed from Improved REST support to Improved REST support (TODO: Mostly Reviews)

#17 Updated by Bastian Waidelich almost 2 years ago

  • Subject changed from Improved REST support (TODO: Mostly Reviews) to Improved REST support

Status of deliverables

  • MUST: more flexible request handling

Request handling has been greatly improved with the "more flexible parsing of body arguments" (#45293, under review).
With this change the parsing of custom media types can be achieved by using/implementing a TypeConverter. Support for basic XML/JSON based content is already built-in.
The type conversion is only invoked as soon as the arguments are really accessed. This will also improve performance in some cases.

  • MUST: Routing improvements

With the possibility to "bind routes to HTTP methods" (#27117, merged) it is possible to create RESTful services without having to use the experimental RestController provided by Flow.
In conjunction with the "nested SubRoutes" feature (#43966, merged) it's easy to create an application with RESTful URIs for multiple resources without having to specify all CRUD routes multiple times.

In addition the RestController will be cleaned up and marked deprecated with https://review.typo3.org/11704/

  • MUST: session-less authentication

With #45282 Flow now only starts a session if the configured authentication mechanism needs it allowing developers to create custom (e.g. header based) authentication implementations that won't create a session cookie.

  • MUST: solid test coverage

All new code is properly covered with unit tests and (where applicable) functional tests

  • MUST: documentation

All new code is properly documented in code. New/modified behavior was added/adjusted on http://docs.typo3.org/flow/TYPO3FlowDocumentation/TheDefinitiveGuide/

  • COULD: improved error handling

Even though this is technically a very easy thing to do, I haven't yet found a good standard for non-HTML based exceptions. See comments at #43569

  • COULD: exemplary (mobile) client that interacts with the TYPO3CR

I didn't come around creating a client for the TYPO3CR yet. But I created quite some github repositories demonstrating how to consume/expose REST APIs (https://github.com/bwaidelich/). "Official" examples will follow

conclusion

This work package caused me quite a lot of fun and headache. I'm convinced that we have a much stronger request handling foundation now and while dealing on the "bowels" of Flow I stumbled upon many other (partly related) issues and challenges leading to a total number of > 20 merges.
There is still a lot to improve, I'll definitely keep working on REST support also in regards to Neos!

#18 Updated by Bastian Waidelich over 1 year ago

  • Status changed from Accepted to Resolved

Also available in: Atom PDF