Uploaded image for project: 'eZ Publish / Platform'
  1. eZ Publish / Platform
  2. EZP-21176

Prevent REST hrefs without prefix in payloads

    Details

    • Sprint:
      Aconcagua Sprint 3
    • Story Points:
      1

      Description

      Situation in 5.0 & 5.1

      Due to the dual router situation we've had in 5.1 & 5.2, it is possible to ignore the REST prefix (/api/ezp/v2) when referencing elements in REST payloads:

      This will be accepted:

      POST /api/ezp/v2/content/objects/42/locations HTTP/1.1
       
      <?xml version="1.0" encoding="UTF-8"?>
      <LocationCreate>
        <ParentLocation href="/content/locations/1/43" />
      </LocationCreate>
      

      While this is the correct one:

      POST /api/ezp/v2/content/objects/42/locations HTTP/1.1
       
      <?xml version="1.0" encoding="UTF-8"?>
      <LocationCreate>
        <ParentLocation href="/api/ezp/v2/content/locations/1/43" />
      </LocationCreate>
      

      Our documentation in regards to this is a bit of a grey area. The spec, that acts as a reference doc, doesn't even have the concept of a prefix.

      Actions

      Update the spec

      • add an introduction paragraph that explains this prefix, and reminds the basics of HATEOAS.

        Issue Links

          Activity

          Hide
          André Rømcke added a comment - - edited

          @Christian Bacher / @Bertrand Dunogier: In the wake of the JS REST client issue from @[~damien.pobel@ez.no] about having to have domain and prefix separated we talked about this should not be needed as prefix can be anything, even the domain only. So with that in mind it would be more beneficial that 5.2 only returned relative urls relative to the endpoint, so REST server doesn't need to know about any of the Symfony setup surrounding this and no need to inject this.

          Why:
          Currently, as of this patch, a Rest client gets an endpoint (includes domain + optional siteaccess url part + REST prefix) and then start to fetch info, however it gets urls with prefix back, which is exactly why Damien voiced that REST client need both domain and prefix as it now needs to append domain to the urls without prefix ending up twice in the url.

          Instead:
          So to not have to have to deal with buggy string comparison in every rest client to extract the domain (and potentially SiteAccess url piece which is before REST prefix in URI), and to not have to make REST server aware of the Symfony details like prefix: Lets just return the relative url, relative to the end point. In this scenario REST client always only have to deal with <end/point/> + <relative/url> to get the full URI.

          Bonus:
          As opposed to using absolute urls to solve the dilemma in the "Why", using REST only relative url's is better for cache as it can be shared across several SiteAccesses, the REST endpoint can if we want to be different from one SiteAccess to another.

          Show
          André Rømcke added a comment - - edited @ Christian Bacher / @ Bertrand Dunogier : In the wake of the JS REST client issue from @ [~damien.pobel@ez.no] about having to have domain and prefix separated we talked about this should not be needed as prefix can be anything, even the domain only. So with that in mind it would be more beneficial that 5.2 only returned relative urls relative to the endpoint, so REST server doesn't need to know about any of the Symfony setup surrounding this and no need to inject this. Why: Currently, as of this patch, a Rest client gets an endpoint (includes domain + optional siteaccess url part + REST prefix) and then start to fetch info, however it gets urls with prefix back, which is exactly why Damien voiced that REST client need both domain and prefix as it now needs to append domain to the urls without prefix ending up twice in the url. Instead: So to not have to have to deal with buggy string comparison in every rest client to extract the domain (and potentially SiteAccess url piece which is before REST prefix in URI), and to not have to make REST server aware of the Symfony details like prefix: Lets just return the relative url, relative to the end point. In this scenario REST client always only have to deal with <end/point/> + <relative/url> to get the full URI. Bonus: As opposed to using absolute urls to solve the dilemma in the "Why", using REST only relative url's is better for cache as it can be shared across several SiteAccesses, the REST endpoint can if we want to be different from one SiteAccess to another.
          Hide
          Bertrand Dunogier added a comment -

          But relative to what ? To the requested resource ? Isn't that awfully complicated ?

          If we don't say anywhere what the base URL is, relative doesn't make any sense, does it ?

          Show
          Bertrand Dunogier added a comment - But relative to what ? To the requested resource ? Isn't that awfully complicated ? If we don't say anywhere what the base URL is, relative doesn't make any sense, does it ?
          Hide
          André Rømcke added a comment - - edited

          The client already knows the base url as it's the endpoint, aka "example.com/api/ezp/v2".

          But my point is probably partly moot as there will never be a siteaccess in url for REST as it's repository specific( ? ), and having to configure domain and endpoint is not the end of the world, so I agree we keep it as is and move on with that.

          Show
          André Rømcke added a comment - - edited The client already knows the base url as it's the endpoint, aka "example.com/api/ezp/v2". But my point is probably partly moot as there will never be a siteaccess in url for REST as it's repository specific( ? ), and having to configure domain and endpoint is not the end of the world, so I agree we keep it as is and move on with that.
          Hide
          Marcos Loureiro (Inactive) added a comment -

          @Bertrand Dunogier
          Regarding my previous comment about error 406 returned when the path doesn't contain the prefix ( not acceptable )

          @Spec there is the error 406
          ( https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#1321general-error-codes )
          however it only mention the accept header not accepted, should it be updated, I mean add the case when the prefix missing to the doc?

          Show
          Marcos Loureiro (Inactive) added a comment - @ Bertrand Dunogier Regarding my previous comment about error 406 returned when the path doesn't contain the prefix ( not acceptable ) @Spec there is the error 406 ( https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#1321general-error-codes ) however it only mention the accept header not accepted, should it be updated, I mean add the case when the prefix missing to the doc?
          Show
          Bertrand Dunogier added a comment - Spec updated in https://github.com/ezsystems/ezpublish-kernel/commit/769d3e1aab8a9700b6ae7d193c06d3b82b141c02 .

            People

            • Assignee:
              Unassigned
              Reporter:
              Bertrand Dunogier
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Time Tracking

                Estimated:
                Original Estimate - 1 day Original Estimate - 1 day
                1d
                Remaining:
                Remaining Estimate - 0 minutes
                0m
                Logged:
                Time Spent - 1 day, 3 hours
                1d 3h

                  Agile