Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-799

Define Key-As-Segment URL convention for resource paths

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_ERRATA02
    • Fix Version/s: V4.01_WD01
    • Component/s: URL Conventions
    • Labels:
    • Environment:

      Simplified Syntax;[Proposed]

    • Proposal:
      Hide

      Key-as-Segment uses the (primary) key of an entity type. 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 (continue to) 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 or doubled

      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')

      Show
      Key-as-Segment uses the (primary) key of an entity type. 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 (continue to) 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 or doubled 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')
    • Resolution:
      Show
      https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59028/odata-v4.01-wd01-part1-protocol.docx https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59029/odata-v4.01-wd01-part2-url-conventions.docx

      Description

      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.

        Attachments

          Activity

            People

            • Assignee:
              mikep Michael Pizzo
              Reporter:
              handl Ralf Handl
            • Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: