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

Allow describing possible responses to requests for a particular resource (public comment c201510e00019)

    XMLWordPrintable

    Details

    • Type: New Feature
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Vocabularies
    • Labels:
      None
    • Environment:

      Proposed

    • Proposal:
      Hide

      Add a property ErrorResponses to the Capabilities terms InsertRestrictions, UpdateRestrictions, DeleteRestrictions, ReadRestrictions, and OperationRestrictions:

      <Property Name="ErrorResponses" Type="Collection(Capabilities.HttpResponse)">
  <Annotation Term="Core.Description" String="Possible HTTP Responses returned by the request." />
</Property>

      The structure of this property is:

      <ComplexType Name="HttpResponse">
  <Property Name="StatusCode" Type="Edm.String">
    <Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" />
  </Property>
  <Property Name="Description" Type="Edm.String">
    <Annotation Term="Core.Description" String="Human-readable description of the response code." />
    <Annotation Term="Core.IsLanguageDependent" />
  </Property>
</ComplexType>
      Show
      Add a property  ErrorResponses to the Capabilities terms  InsertRestrictions , UpdateRestrictions , DeleteRestrictions ,  ReadRestrictions , and  OperationRestrictions : <Property Name= "ErrorResponses" Type= "Collection(Capabilities.HttpResponse)" > <Annotation Term= "Core.Description" String= "Possible HTTP Responses returned by the request." /> </Property> The structure of this property is: <ComplexType Name= "HttpResponse" > <Property Name= "StatusCode" Type= "Edm.String" > <Annotation Term= "Core.Description" String= "HTTP status code of the response, e.g. 400, 403, 501" /> </Property> <Property Name= "Description" Type= "Edm.String" > <Annotation Term= "Core.Description" String= "Human-readable description of the response code." /> <Annotation Term= "Core.IsLanguageDependent" /> </Property> </ComplexType>
    • Resolution:
      Hide

      https://github.com/oasis-tcs/odata-vocabularies/pull/190

      https://github.com/oasis-tcs/odata-openapi/pull/212 

       

      Show
      https://github.com/oasis-tcs/odata-vocabularies/pull/190 https://github.com/oasis-tcs/odata-openapi/pull/212    

      Description

      Jeff Wight proposes to add a term that allows describing possible code values in OData error responses, see https://lists.oasis-open.org/archives/odata-comment/201510/msg00019.html

      Example:

      <Annotation Term="Core.ErrorCodes">
  <Collection>
    <Record>
      <PropertyValue Property="HttpMethod" String="GET" />
      <PropertyValue Property="HttpStatusCode" String="400" />
      <PropertyValue Property="ODataErrorCode" String="QueryFilterFunctionNotSupported" />
      <PropertyValue Property="Description"
 String="This error indicates that a request was made with a filter function that isn’t supported on this entity set. Please refer to the Capabilities.FilterFunctions annotation on this entity set for a list of supported functions, and the exact error message for which function usage triggered this error." />
    </Record>
  </Collection>
</Annotation>

      Definition

      <Term Name="ErrorCodes" Type="Collection(Core.ErrorCodeType)" AppliesTo="EntitySet Singleton ActionImport FunctionImport Action Function">
  <Annotation Term="Core.Description" String="Describes possible error codes in OData responses" />
  <Annotation Term="Core.LongDescription" String="The list need not be complete. It may be used to generate API documentation, so restricting it to the most common and most important errors may increase readability." />
</Term>

<ComplexType Name="ErrorCodeType">
  <Property Name="HttpMethod" Type="Edm.String">
    <Annotation Term="Core.Description" String="Request verb of the HTTP request, e.g. GET, POST, PATCH, DELETE" />
  </Property>
  <Property Name="HttpStatusCode" Type="Edm.String">
    <Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" />
  </Property>
  <Property Name="ODataErrorCode" Type="Edm.String">
    <Annotation Term="Core.Description" String="Language-independent, machine-readable OData error code" />
  </Property>
  <Property Name="Description" Type="Edm.String">
    <Annotation Term="Core.Description" String="Human-readable description of the error situation" />
  </Property>
</ComplexType>

        Attachments

          Activity

            People

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

              Dates

              • Created:
                Updated:
                Resolved: