[OASIS Issue Tracker] Updated: (ODATA-527) Relative URLs in OData and the ability to put OData services behind an HTTP proxy

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

     [ http://tools.oasis-open.org/issues/browse/ODATA-527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Ralf Handl updated ODATA-527:
-----------------------------

    Description: 
It is often necessary to place an OData producer behind a (reverse) proxy. 

HTTP proxies will alter request URLs. They typically change:
- the scheme (http or https)
- the host
- the port
They can change the path, typically by exchanging a prefix portion.
They also can add, remove, or modify HTTP request and response headers.

They cannot alter message bodies without knowledge beyond HTTP, in our case knowledge of the OData formats
- CSDL
- Atom
- JSON
- anything we might want to add in the future

So message bodies should only contain URLs that need not be altered by HTTP proxies.

This affects request bodies created by OData consumers and response bodies created by OData producers.

Two typical candidates for such "proxy-safe" URLs are
- absolute URLs outside of the domain shielded by the proxy
- relative URLs that are relative to something the proxy can easily alter

In addition resolution of relative URLs should be possible with the information contained in the request-response message pair and no out-of-band knowledge beyond the OData specifications. Note that the service root is out-of-band knowledge: it cannot be calculated from the context URL which is based on the metadata URL, and the service root URL is not a specified part of the metadata document. 

Problems with the current rules for relative URLs
- Content-Location header: this header is only available in responses. Also it has special meaning if it deviates from the request URL, so having it in the resolution chain only adds problems and does not add any value
- Batch requests allow three formats for request URLs in the batch body, and the relative format is mentioned last.

  was:
It is often desirable to place an OData producer behind a (reverse) proxy. 

This works best if all URLs in requests and responses are relative, so proxies don't have to touch the message bodies.

Interpreting URLs relative to the Content-Location header or the request URL doesn't work well with OData's URL conventions, which are constructed relative to the service root, so URLs starting relative to an entity would have to add ../ segments to go "down" to the service root and then "up" into the related entities. Especially with containment or several function segments this can become painful.

       Proposal: 
Within a message the format-specific rules (xml:base, odata.context, odata.type) for resolving relative URLs apply. 

Remove the current rule for resolution relative to the Content-Location.

Relative URLs are ultimately relative to the request URL

Clients MUST provide URLs relative to the request URL in request bodies whenever possible (i.e. same scheme, host, and port as the request URL).

This includes the request URLs of requests nested in a batch request. The relative format is preferred, and the other formats are only allowed for requests not relative to the $batch resource.

  was:
Within a message the format-specific rules (xml:base, odata.context, odata.type) for resolving relative URLs apply.

Define a special header OData-BasePath that, if present, is the base path for URLs that are still relative after applying the format-specific rules. This header can be easily rewritten by proxies.

The host and port are contained in the standard Host header, so these can be rewritten separately.

If the OData-BasePath header is not present, the service root is used as the base path.

The header is intentionally named BasePath to support multi-service scenarios where several interrelated services use a common path prefix, e.g.

   http://machine:40/odata/HR.svc
   http://machine:40/odata/Procurement.svc

This allows e.g. the Procurement service to contain navigation links of the form

   HR.svc/Employees(123)

that then are combined with 

   Host: machine:40
   OData-BasePath: /odata/

Two possible special cases are
- the base path is a single / meaning that the services just share the same logical host
- the base path is the service root path
The latter is the natural choice for isolated services not linking to other services,  so this is the default if no header is present.

Services will specify the header if they have to produce links to other services.

Clients need not specify this header at all. 


Simplified the proposal and described the rationale leading to it.

@Hubert: this should address your team's concerns. Unfortunately it also excludes your preferred solution: the service root URL is currently out-of-band knowledge and does not qualify for resolution of relative URLs.

> Relative URLs in OData and the ability to put OData services behind an HTTP proxy
> ---------------------------------------------------------------------------------
>
>                 Key: ODATA-527
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-527
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData ATOM Format , OData CSDL, OData JSON Format, OData Protocol 
>    Affects Versions: V4.0_CS01
>         Environment: [Proposed]
>            Reporter: Ralf Handl
>             Fix For: V4.0_CSD03
>
>
> It is often necessary to place an OData producer behind a (reverse) proxy. 
> HTTP proxies will alter request URLs. They typically change:
> - the scheme (http or https)
> - the host
> - the port
> They can change the path, typically by exchanging a prefix portion.
> They also can add, remove, or modify HTTP request and response headers.
> They cannot alter message bodies without knowledge beyond HTTP, in our case knowledge of the OData formats
> - CSDL
> - Atom
> - JSON
> - anything we might want to add in the future
> So message bodies should only contain URLs that need not be altered by HTTP proxies.
> This affects request bodies created by OData consumers and response bodies created by OData producers.
> Two typical candidates for such "proxy-safe" URLs are
> - absolute URLs outside of the domain shielded by the proxy
> - relative URLs that are relative to something the proxy can easily alter
> In addition resolution of relative URLs should be possible with the information contained in the request-response message pair and no out-of-band knowledge beyond the OData specifications. Note that the service root is out-of-band knowledge: it cannot be calculated from the context URL which is based on the metadata URL, and the service root URL is not a specified part of the metadata document. 
> Problems with the current rules for relative URLs
> - Content-Location header: this header is only available in responses. Also it has special meaning if it deviates from the request URL, so having it in the resolution chain only adds problems and does not add any value
> - Batch requests allow three formats for request URLs in the batch body, and the relative format is mentioned last.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira