[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.CustomParameter)" AppliesTo="EntityContainer"> <Annotation Term="Core.Description" String="Custom headers that are supported/required for the service" /> <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.CustomParameter)" AppliesTo="EntityContainer"> <Annotation Term="Core.Description" String="Custom query options that are supported/required for the service" /> <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.CustomParameter)" AppliesTo="EntityContainer"> <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.CustomParameter)" AppliesTo="EntityContainer"> <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 > Reporter: Ralf Handl > Assignee: 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]