[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] (ODATA-1099) Add annotations to describe custom query options and custom headers
[ https://issues.oasis-open.org/browse/ODATA-1099?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael Pizzo updated ODATA-1099:
---------------------------------
Proposal:
See https://github.com/oasis-tcs/odata-vocabularies/blob/ODATA-1099/vocabularies/Org.OData.Capabilities.V1.md#CustomHeaders
<Term Name="CustomHeaders" Type="Collection(Capabilities.CustomParamater)" AppliesTo="EntitySet Singleton Action ActionImport Function FunctionImport">
<Annotation Term="Core.Description" String="Custom headers that are supported/required for the annotated resource" />
<Annotation Term="Core.Example">
<Annotation Term="Capabilities.CustomHeaders">
<Collection>
<Record>
<PropertyValue Property="Name" String="X-CSRF-Token" />
<PropertyValue Property="Description" String="Token to protect against Cross-Site Request Forgery attacks" />
<PropertyValue Property="DocumentationURL"
String="https://help.sap.com/viewer/68bf513362174d54b58cddec28794093/7.51.1/en-US/b35c22518bc72214e10000000a44176d.html"; />
<PropertyValue Property="Required" Bool="true" />
<PropertyValue Property="ExampleValues">
<Collection>
<Record>
<PropertyValue Property="Value" String="Fetch" />
<PropertyValue Property="Description"
String="Can be used on HEAD request to the service document for obtaining a new CSRF token. This token must then be sent in subsequent requests to resources of the service." />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
</Annotation>
</Term>
<Term Name="CustomQueryOptions" Type="Collection(Capabilities.CustomParamater)" AppliesTo="EntityContainer EntitySet Singleton Action ActionImport Function FunctionImport">
<Annotation Term="Core.Description" String="Custom query options that are supported/required for the annotated resource" />
<Annotation Term="Core.LongDescription"
String="If the entity container is annotated, the query option is supported/required by all resources in that container." />
<Annotation Term="Core.Example">
<Annotation Term="Capabilities.CustomQueryOptions">
<Collection>
<Record>
<PropertyValue Property="Name" String="odata-debug" />
<PropertyValue Property="Description" String="Debug support for OData services" />
<PropertyValue Property="DocumentationURL" String="https://olingo.apache.org/doc/odata2/tutorials/debug.html"; />
<PropertyValue Property="Required" Bool="false" />
<PropertyValue Property="ExampleValues">
<Collection>
<Record>
<PropertyValue Property="Value" String="html" />
<PropertyValue Property="Description"
String="Service responds with self-contained HTML document that can conveniently viewed in a browser and gives access to the response body, response headers, URL parsing information, and stack trace" />
</Record>
<Record>
<PropertyValue Property="Value" String="json" />
<PropertyValue Property="Description"
String="Service responds with JSON document that contains the same information as the HTML debug response" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
</Annotation>
</Term>
<ComplexType Name="CustomParameter">
<Annotation Term="Core.Description" String="A custom parameter is either a header or a query option" />
<Annotation Term="Core.LongDescription"
String="The type of a custom parameter is always a string. Restrictions on the parameter values can be expressed by annotating the record expression describing the parameter with terms from the Validation vocabulary, e.g. Validation.Pattern or Validation.AllowedValues." />
<Property Name="Name" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Name of the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Description of the custom parameter" />
</Property>
<Property Name="DocumentationURL" Type="Edm.String">
<Annotation Term="Core.IsURL" />
<Annotation Term="Core.Description" String="URL of related documentation" />
</Property>
<Property Name="Required" Type="Edm.Boolean" Nullable="false">
<Annotation Term="Core.Description" String="true: parameter is required, false or not specified: parameter is optional" />
</Property>
<Property Name="ExampleValues" Type="Collection(Capabilities.CustomParameterExampleValue)" Nullable="false">
<Annotation Term="Core.Description" String="Example values for the custom parameter" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameterExampleValue">
<Property Name="Value" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Example value for the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Description of the example value" />
</Property>
</ComplexType>
was:
See https://github.com/oasis-tcs/odata-vocabularies/blob/ODATA-1099/vocabularies/Org.OData.Capabilities.V1.md#CustomHeaders
<Term Name="CustomHeaders" Type="Collection(Capabilities.CustomParmater)" AppliesTo="EntitySet Singleton Action ActionImport Function FunctionImport">
<Annotation Term="Core.Description" String="Custom headers that are supported/required for the annotated resource" />
<Annotation Term="Core.Example">
<Annotation Term="Capabilities.CustomHeaders">
<Collection>
<Record>
<PropertyValue Property="Name" String="X-CSRF-Token" />
<PropertyValue Property="Description" String="Token to protect against Cross-Site Request Forgery attacks" />
<PropertyValue Property="DocumentationURL"
String="https://help.sap.com/viewer/68bf513362174d54b58cddec28794093/7.51.1/en-US/b35c22518bc72214e10000000a44176d.html"; />
<PropertyValue Property="Required" Bool="true" />
<PropertyValue Property="ExampleValues">
<Collection>
<Record>
<PropertyValue Property="Value" String="Fetch" />
<PropertyValue Property="Description"
String="Can be used on HEAD request to the service document for obtaining a new CSRF token. This token must then be sent in subsequent requests to resources of the service." />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
</Annotation>
</Term>
<Term Name="CustomQueryOptions" Type="Collection(Capabilities.CustomParmater)" AppliesTo="EntityContainer EntitySet Singleton Action ActionImport Function FunctionImport">
<Annotation Term="Core.Description" String="Custom query options that are supported/required for the annotated resource" />
<Annotation Term="Core.LongDescription"
String="If the entity container is annotated, the query option is supported/required by all resources in that container." />
<Annotation Term="Core.Example">
<Annotation Term="Capabilities.CustomQueryOptions">
<Collection>
<Record>
<PropertyValue Property="Name" String="odata-debug" />
<PropertyValue Property="Description" String="Debug support for OData services" />
<PropertyValue Property="DocumentationURL" String="https://olingo.apache.org/doc/odata2/tutorials/debug.html"; />
<PropertyValue Property="Required" Bool="false" />
<PropertyValue Property="ExampleValues">
<Collection>
<Record>
<PropertyValue Property="Value" String="html" />
<PropertyValue Property="Description"
String="Service responds with self-contained HTML document that can conveniently viewed in a browser and gives access to the response body, response headers, URL parsing information, and stack trace" />
</Record>
<Record>
<PropertyValue Property="Value" String="json" />
<PropertyValue Property="Description"
String="Service responds with JSON document that contains the same information as the HTML debug response" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
</Annotation>
</Term>
<ComplexType Name="CustomParameter">
<Annotation Term="Core.Description" String="A custom parameter is either a header or a query option" />
<Annotation Term="Core.LongDescription"
String="The type of a custom parameter is always a string. Restrictions on the parameter values can be expressed by annotating the record expression describing the parameter with terms from the Validation vocabulary, e.g. Validation.Pattern or Validation.AllowedValues." />
<Property Name="Name" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Name of the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String">
<Annotation Term="Core.Description" String="Description of the custom parameter" />
</Property>
<Property Name="DocumentationURL" Type="Edm.String">
<Annotation Term="Core.IsURL" />
<Annotation Term="Core.Description" String="URL of related documentation" />
</Property>
<Property Name="Required" Type="Edm.Boolean" Nullable="false">
<Annotation Term="Core.Description" String="true: parameter is required, false or not specified: parameter is optional" />
</Property>
<Property Name="ExampleValues" Type="Collection(Capabilities.CustomParameterExampleValue)" Nullable="false">
<Annotation Term="Core.Description" String="Example values for the custom parameter" />
</Property>
</ComplexType>
<ComplexType Name="CustomParameterExampleValue">
<Property Name="Value" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Example value for the custom parameter" />
</Property>
<Property Name="Description" Type="Edm.String" Nullable="false">
<Annotation Term="Core.Description" String="Description of the example value" />
</Property>
</ComplexType>
> Add annotations to describe custom query options and custom headers
> -------------------------------------------------------------------
>
> Key: ODATA-1099
> URL: https://issues.oasis-open.org/browse/ODATA-1099
> Project: OASIS Open Data Protocol (OData) TC
> Issue Type: New Feature
> Components: Vocabularies
> Affects Versions: V4.0_CSD01
> Environment: Proposed
> Reporter: Ralf Handl
> Fix For: V4.0_CSD02
>
>
> Some services support custom query options, either across the board, or for specific resources or resource types.
> Other services support or even require custom headers, e.g. for CSRF protection.
> We need a way to express in metadata which custom query options and custom headers are available / required where.
--
This message was sent by Atlassian JIRA
(v6.2.2#6258)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]