[OASIS Issue Tracker] (ODATA-799) Define Key-As-Segment URL convention for resource paths

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

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

Michael Pizzo updated ODATA-799:
--------------------------------

    Proposal: 
Key-as-Segment uses the (primary) key of an entity type. The number and sequence of <PropertyRef> elements within the <Key> defines the number and sequence of path segments that have to be attached to the path of the collection to identify an item in a collection.
Primitive types are represented in path key segments without "single quote decoration" or "double single quotes within" and use standard percent-encoding to map them into the lexical space of URL path segments.

4.01 Services that support key-as-segment syntax (for single-part keys only) should support the following precedence rules:

Following an entity collection segment: 
i.	Try to match an OData segment (starting with “$”)
ii.	Try to match an alias-qualified bound action name, bound function overload, or type name
iii.	Try to match a namespace-qualified bound action name, bound function overload, or type name
iv.	Try to match an unqualified bound action name, bound function overload, or type name in a default namespace
v.	Treat as a key

Notes:
1. For maximum interoperability, services SHOULD also support parens format, to avoid ambiguity, and to support multi-part keys. Note that, if they do not support the parens format, they must include the @odata.id, @odata.editlink, or @odata.readlink, as appropriate.
2. The syntax of ContextUrl always uses parens syntax
3. Forward slashes in key values must be percent-encoded  
4. Single quotes within key values do not need to be percent-encoded

Example 3 with key-as-segment syntax and current syntax
single quote can be literal within string or percent-encoded and isn't doubled (using ~/ as a shortcut for the service root)
~/People/O'Neil
~/People/O%27Neil

~/People('O''Neil')
~/People(%27O%27%27Neil%27) 
~/People%28%27O%27%27Neil%27%29

Forward-slash within string must be percent-encoded just as in paren syntax
~/Categories/Smartphone%2FTablet
~/Categories('Smartphone%2FTablet')



  was:
Key-as-Segment uses the (primary) key of an entity type. The number and sequence of <PropertyRef> elements within the <Key> defines the number and sequence of path segments that have to be attached to the path of the collection to identify an item in a collection.
Primitive types are represented in path key segments without "single quote decoration" or "double single quotes within" and use standard percent-encoding to map them into the lexical space of URL path segments.

Example 3 with key-as-segment syntax and current syntax
single quote can be literal within string or percent-encoded and isn't doubled (using ~/ as a shortcut for the service root)
~/People/O'Neil
~/People/O%27Neil

~/People('O''Neil')
~/People(%27O%27%27Neil%27) 
~/People%28%27O%27%27Neil%27%29

Forward-slash within string must be percent-encoded just as in paren syntax
~/Categories/Smartphone%2FTablet
~/Categories('Smartphone%2FTablet')




> Define Key-As-Segment URL convention for resource paths
> -------------------------------------------------------
>
>                 Key: ODATA-799
>                 URL: https://issues.oasis-open.org/browse/ODATA-799
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Improvement
>          Components: OData URL Conventions
>    Affects Versions: V4.0_ERRATA02
>         Environment: Simplified Syntax;[Proposed]
>            Reporter: Ralf Handl
>            Assignee: Michael Pizzo
>              Labels: AdoptionBlocker
>             Fix For: V4.01_WD01
>
>
> Typical web APIs use path segments for key access to collection elements:
> ~/Users
> ~/Users/42
> Specify how such a URL convention would look like, considering
> - multi-part keys
> - the Edm primitive type system
> - bound actions/functions on entity-set level
> - context URLs for contained entities which include the key
> - relative context URLs
> Consider notation that allows context URLs to be relative to the service root.



--
This message was sent by Atlassian JIRA
(v6.2.2#6258)