Serving OData APIs ​

Feature Overview ​

OData is an OASIS standard, which essentially enhances plain REST with standardized system query options like $select, $expand, $filter, etc. Find a rough overview of the feature coverage in the following table:

• ⁽¹⁾ The elements to be searched are specified with the @cds.search annotation.
• ⁽²⁾ The navigation path identifying the collection can only contain one segment.

System query options can also be applied to an expanded navigation property (nested within $expand):

Learn more in the Getting Started guide on odata.org.Learn more in the tutorials Take a Deep Dive into OData.

PATCH Entity Collection with Mass Data (Java) ​

With OData v4, you can update a collection of entities with a single PATCH request. The resource path of the request targets the entity collection and the body of the request is given as a delta payload:

PATCH /CatalogService/Books
Content-Type: application/json

{
    "@context": "#$delta",
    "value": [
        {
            "ID": 17,
            "title": "CAP - what's new in 2023",
            "price": 29.99,
            "author_ID": 999
        },
        {
            "ID": 85,
            "price": 9.99
        },
        {
            "ID": 42,
            "@removed": { "reason": "deleted" }
        }
    ]
}

PATCH requests with delta payload are executed using batch delete and upsert statements, and are more efficient than OData batch requests.

Use PATCH on entity collections for uploading mass data using a dedicated service, which is secured using role-based authorization. Delta updates must be explicitly enabled by annotating the entity with

@Capabilities.UpdateRestrictions.DeltaUpdateSupported

Limitations:

• Conflict detection via ETags is not supported.
• Draft flow is bypassed, IsActiveEntity has to be true.
• Draft locks are ignored, active entities are updated or deleted w/o canceling drafts.
• Added and deleted links are not supported.
• The header Prefer=representation is not yet supported.
• The continue-on-error preference is not yet supported.
• The generic CAP handler support for upsert is limited, for example, audit logging is not supported.

Mapping of CDS Types ​

The table below lists CDS's built-in types and their mapping to the OData EDM type system.

⁽¹⁾ Mapping can be changed with, for example, @odata.Type='Edm.String'

OData V2 has the following differences:

Overriding Type Mapping ​

Override standard type mappings using the annotation @odata.Type first, and then additionally define @odata {MaxLength, Precision, Scale, SRID}.

@odata.Type is effective on scalar CDS types only and the value must be a valid OData (EDM) primitive type for the specified protocol version. Unknown types and non-matching facets are silently ignored. No further value constraint checks are applied.

They allow, for example, to produce additional OData EDM types which are not available in the standard type mapping. This is done during the import of external service APIs, see Using Services.

entity Foo {
  ...,
  @odata: { Type: 'Edm.GeometryPolygon', SRID: 0 }
  geoCollection : LargeBinary;
};

Another prominent use case is the CDS type UUID, which maps to Edm.Guid by default. However, the OData standard puts up restrictive rules for Edm.Guid values - for example, only hyphenated strings are allowed - which can conflict with existing data. Therefore, you can override the default mapping as follows:

entity Books {
  key ID : UUID @odata.Type:'Edm.String';
  ...
}

entity Foo {
  // ...
  @odata: {Type: 'Edm.Decimal', Scale: 'floating' }
  str: String(17) default '17.4';
}

<Property Name="str" Type="Edm.Decimal" Scale="floating" DefaultValue="17.4"/>

OData Annotations ​

The following sections explain how to add OData annotations to CDS models and how they're mapped to EDMX outputs. Only annotations defined in the vocabularies mentioned in section Annotation Vocabularies are considered in the translation.

Terms and Properties ​

OData defines a strict two-fold key structure composed of @<Vocabulary>.<Term> and all annotations are always specified as a Term with either a primitive value, a record value, or collection values. The properties themselves may, in turn, be primitives, records, or collections.

Example ​

@Common.Label: 'Customer'
@Common.ValueList: {
  Label: 'Customers',
  CollectionPath: 'Customers'
}
entity Customers { }

This is represented in CSN as follows:

{"definitions":{
  "Customers":{
    "kind": "entity",
    "@Common.Label": "Customer",
    "@Common.ValueList.Label": "Customers",
    "@Common.ValueList.CollectionPath": "Customers"
  }
}}

And would render to EDMX as follows:

<Annotations Target="MyService.Customers">
  <Annotation Term="Common.Label" String="Customer"/>
  <Annotation Term="Common.ValueList">
    <Record Type="Common.ValueListType">
      <PropertyValue Property="Label" String="Customers"/>
      <PropertyValue Property="CollectionPath" String="Customers"/>
    </Record>
  </Annotation>
</Annotations>

For each annotated target definition in CSN, the rules for restructuring from CSN sources are:

1. Annotations with a single-identifier key are skipped (as OData annotations always have a @Vocabulary.Term... key signature).
2. All individual annotations with the same @<Vocabulary.Term> prefix are collected.
3. If there is only one annotation without a suffix, → that one is a scalar or array value of an OData term.
4. If there are more annotations with suffix key parts → it's a record value for the OData term.

Qualified Annotations ​

OData foresees qualified annotations, which essentially allow to specify different values for a given property. CDS syntax for annotations was extended to also allow appending OData-style qualifiers after a # sign to an annotation key, but always only as the last component of a key in the syntax.

For example, this is supported:

@Common.Label: 'Customer'
@Common.Label#Legal: 'Client'
@Common.Label#Healthcare: 'Patient'
@Common.ValueList: {
  Label: 'Customers',
  CollectionPath:'Customers'
}
@Common.ValueList#Legal: {
  Label: 'Clients',
  CollectionPath:'Clients'
}

and would render as follows in CSN:

{
  "@Common.Label": "Customer",
  "@Common.Label#Legal": "Clients",
  "@Common.Label#Healthcare": "Patients",
  "@Common.ValueList.Label": "Customers",
  "@Common.ValueList.CollectionPath": "Customers",
  "@Common.ValueList#Legal.Label": "Clients",
  "@Common.ValueList#Legal.CollectionPath": "Clients",
}

Note that there's no interpretation and no special handling for these qualifiers in CDS. You have to write and apply them in exactly the same way as your chosen OData vocabularies specify them.

Primitives ​

Primitive annotation values, meaning Strings, Numbers, true, and false are mapped to corresponding OData annotations as follows:

@Some.Boolean: true
@Some.Integer: 1
@Some.Number: 3.14
@Some.String: 'foo'

<Annotation Term="Some.Boolean" Bool="true"/>
<Annotation Term="Some.Integer" Int="1"/>
<Annotation Term="Some.Number" Decimal="3.14"/>
<Annotation Term="Some.String" String="foo"/>

Rendering a null value must be done as dynamic expression:

@Some.Null: { $edmJson: { $Null } }

<Annotation Term="Some.Null">
  <Null/>
</Annotation>

Have a look at our CAP SFLIGHT sample, showcasing the usage of OData annotations.

Records ​

The @Some annotation isn't a valid term definition. The following example illustrates the rendering of record values.

Record-like source structures are mapped to <Record> nodes in EDMX, with primitive types translated analogously to the above:

@Some.Record: {
  Null: null,
  Boolean: true,
  Integer: 1,
  Number: 3.14,
  String: 'foo'
}

<Annotation Term="Some.Record">
  <Record>
    <PropertyValue Property="Null"><Null/></PropertyValue>
    <PropertyValue Property="Boolean" Bool="true"/>
    <PropertyValue Property="Integer" Int="1"/>
    <PropertyValue Property="Number" Decimal="3.14"/>
    <PropertyValue Property="String" String="foo"/>
  </Record>
</Annotation>

If possible, the type of the record in OData is deduced from the information in the OData Annotation Vocabularies:

@Common.ValueList: {
  CollectionPath: 'Customers'
}

<Annotation Term="Common.ValueList">
  <Record Type="Common.ValueListType">
    <PropertyValue Property="CollectionPath" String="Customers"/>
  </Record>
</Annotation>

Frequently, the OData record type cannot be determined unambiguously, for example if the type found in the vocabulary is abstract. Then you need to explicitly specify the type by adding a property named $Type in the record. For example:

@UI.Facets : [{
  $Type  : 'UI.CollectionFacet',
  ID     : 'Customers'
}]

<Annotation Term="UI.Facets">
  <Collection>
    <Record Type="UI.CollectionFacet">
      <PropertyValue Property="ID" String="Travel"/>
    </Record>
  </Collection>
</Annotation>

There is one exception for a very prominent case: if the deduced record type is UI.DataFieldAbstract, the compiler by default automatically chooses UI.DataField:

@UI.Identification: [{
  Value: deliveryId
}]

<Annotation Term="UI.Identification">
  <Collection>
    <Record Type="UI.DataField">
      <PropertyValue Property="Value" Path="deliveryId"/>
    </Record>
  </Collection>
</Annotation>

To overwrite the default, use an explicit $Type like shown previously.

Have a look at our CAP SFLIGHT sample, showcasing the usage of OData annotations.

Collections ​

The @Some annotation isn't a valid term definition. The following example illustrates the rendering of collection values.

Arrays are mapped to <Collection> nodes in EDMX and if primitives show up as direct elements of the array, these elements are wrapped into individual primitive child nodes of the resulting collection as is. The rules for records and collections are applied recursively:

@Some.Collection: [
  true, 1, 3.14, 'foo',
  { $Type:'UI.DataField', Label:'Whatever', Hidden }
]

<Annotation Term="Some.Collection">
  <Collection>
    <Null/>
    <Bool>true</Bool>
    <Int>1</Int>
    <Decimal>3.14</Decimal>
    <String>foo</String>
    <Record Type="UI.DataField">
      <PropertyValue Property="Label" String="Whatever"/>
      <PropertyValue Property="Hidden" Bool="True"/>
    </Record>
  </Collection>
</Annotation>

References ​

The @Some annotation isn't a valid term definition. The following example illustrates the rendering of reference values.

References in cds annotations are mapped to .Path properties or nested <Path> elements respectively:

@Some.Term: My.Reference
@Some.Record: {
  Value: My.Reference
}
@Some.Collection: [
  My.Reference
]

<Annotation Term="Some.Term" Path="My/Reference"/>
<Annotation Term="Some.Record">
  <Record>
    <PropertyValue Property="Value" Path="My/Reference"/>
  </Record>
</Annotation>
<Annotation Term="Some.Collection">
  <Collection>
    <Path>My/Reference</Path>
  </Collection>
</Annotation>

Use a dynamic expression if the generic mapping can't produce the desired <Path>:

@Some.Term: {$edmJson: {$Path: '/com.sap.foo.EntityContainer/EntityName/FieldName'}}

<Annotation Term="Some.Term">
  <Path>/com.sap.foo.EntityContainer/EntityName/FieldName</Path>
</Annotation>

Enumeration Values ​

Enumeration symbols are mapped to corresponding EnumMember properties in OData.

Here are a couple of examples of enumeration values and the annotations that are generated. The first example is for a term in the Common vocabulary:

@Common.TextFormat: #html

<Annotation Term="Common.TextFormat" EnumMember="Common.TextFormatType/html"/>

The second example is for a (record type) term in the Communication vocabulary:

@Communication.Contact: {
  gender: #F
}

<Annotation Term="Communication.Contact">
  <Record Type="Communication.ContactType">
    <PropertyValue Property="gender" EnumMember="Communication.GenderType/F"/>
  </Record>
</Annotation>

Annotating Annotations ​

OData can annotate annotations. This often occurs in combination with enums like UI.Importance and UI.TextArrangement. CDS has no corresponding language feature. For OData annotations, nesting can be achieved in the following way:

• To annotate a Record, add an additional element to the CDS source structure. The name of this element is the full name of the annotation, including the @. See @UI.Importance in the following example.
• To annotate a single value or a Collection, add a parallel annotation that has the nested annotation name appended to the outer annotation name. See @UI.Criticality and @UI.TextArrangement in the following example.

@UI.LineItem: [
    {Value: ApplicationName, @UI.Importance: #High},
    {Value: Description},
    {Value: SourceName},
    {Value: ChangedBy},
    {Value: ChangedAt}
  ]
@UI.LineItem.@UI.Criticality: #Positive


@Common.Text: Text
@Common.Text.@UI.TextArrangement: #TextOnly

Alternatively, annotating a single value or a Collection by turning them into a structure with an artificial property $value is still possible, but deprecated:

@UI.LineItem: {
  $value:[ /* ... */ ], @UI.Criticality: #Positive
 }

@Common.Text: {
  $value: Text, @UI.TextArrangement: #TextOnly
}

As TextArrangement is common, there's a shortcut for this specific situation:

...
@Common: {
  Text: Text, TextArrangement: #TextOnly
}

In any case, the resulting EDMX is:

<Annotation Term="UI.LineItem">
  <Collection>
    <Record Type="UI.DataField">
      <PropertyValue Property="Value" Path="ApplicationName"/>
      <Annotation Term="UI.Importance" EnumMember="UI.ImportanceType/High"/>
    </Record>
    ...
  </Collection>
  <Annotation Term="UI.Criticality" EnumMember="UI.CriticalityType/Positive"/>
</Annotation>
<Annotation Term="Common.Text" Path="Text">
  <Annotation Term="UI.TextArrangement" EnumMember="UI.TextArrangementType/TextOnly"/>
</Annotation>

Dynamic Expressions ​

OData supports dynamic expressions in annotations. CDS syntax doesn't allow writing expressions in annotation values, but for OData annotations you can use the "edm-json inline mechanism" by providing a dynamic expression as defined in the JSON representation of the OData Common Schema Language enclosed in { $edmJson: { ... }}.

Note that here the CDS syntax for string literals with single quotes ('foo') applies, and that paths are not automatically recognized but need to be written as {$Path: 'fieldName'}. The CDS compiler translates the expression into the corresponding XML representation.

For example, the CDS annotation:

@UI.Hidden: {$edmJson: {$Ne: [{$Path: 'status'}, 'visible']}}

is translated to:

<Annotation Term="UI.Hidden">
  <Ne>
    <Path>status</Path>
    <String>visible</String>
  </Ne>
</Annotation>

sap: Annotations ​

In general, back ends and SAP Fiori UIs understand or even expect OData V4 annotations. You should use those rather than the OData V2 SAP extensions.

If necessary, CDS automatically translates OData V4 annotations to OData V2 SAP extensions when invoked with v2 as the OData version. This means that you shouldn't have to deal with this at all.

Nevertheless, in case you need to do so, you can add sap:... attribute-style annotations as follows:

@sap.applicable.path: 'to_eventStatus/EditEnabled'
  action EditEvent(...) returns SomeType;

Which would render to OData EDMX as follows:

<FunctionImport Name="EditEvent" ...
    sap:applicable-path="to_eventStatus/EditEnabled">
    ...
  </FunctionImport>

The rules are:

• Only strings are supported as values.
• The first dot in @sap. is replaced by a colon :.
• Subsequent dots are replaced by dashes.

Differences to ABAP ​

In contrast to ABAP CDS, we apply a generic, isomorphic approach where names and positions of annotations are exactly as specified in the OData Vocabularies. This has the following advantages:

• Single source of truth — users only need to consult the official OData specs
• Speed — we don't need complex case-by-case mapping logic
• No bottlenecks — we always support the full set of OData annotations
• Bidirectional mapping — we can translate CDS to EDMX and vice versa

Last but not least, it also saves us lots of effort as we don't have to write derivatives of all the OData vocabulary specs.

Annotation Vocabularies ​

When translating a CDS model to an OData API, by default only those annotations are considered that are part of the standard OASIS or SAP vocabularies listed below. You can add further vocabularies to the translation process using configuration.

OASIS Vocabularies ​

SAP Vocabularies ​

Learn more about annotations in CDS and OData and how they work together

Additional Vocabularies ​

Assuming you have a vocabulary com.MyCompany.vocabularies.MyVocabulary.v1, you can set the following configuration option:

{
  "cds": {
    "cdsc": {
      "odataVocabularies": {
        "MyVocabulary": {
          "Alias": "MyVocabulary",
          "Namespace": "com.sap.vocabularies.MyVocabulary.v1",
          "Uri": "<link to vocabulary document>"
        }
      }
    }
  }
}

{
  "cdsc": {
    "odataVocabularies": {
      "MyVocabulary": {
        "Alias": "MyVocabulary",
        "Namespace": "com.sap.vocabularies.MyVocabulary.v1",
        "Uri": "<link to vocabulary document>"
      }
    }
  }
}

With this configuration, all annotations prefixed with MyVocabulary are considered in the translation.

service S {
  @MyVocabulary.MyAnno: 'My new Annotation'
  entity E { /*...*/ };
};

The annotation is added to the OData API, as well as the mandatory reference to the vocabulary definition:

<edmx:Reference Uri="link to vocabulary document">
  <edmx:Include Alias="MyVocabulary" Namespace="com.MyCompany.vocabularies.MyVocabulary.v1"/>
</edmx:Reference>
...
<Annotations Target="S.E">
  <Annotation Term="MyVocabulary.MyAnno" String="My new Annotation"/>
</Annotations>

The compiler neither evaluates the annotation values nor the URI. It is your responsibility to make the URI accessible if required. Unlike for the standard vocabularies listed above, the compiler has no access to the content of the vocabulary, so the values are translated completely generically.

Data Aggregation ​

Data aggregation in OData V4 is leveraged by the $apply system query option, which defines a pipeline of transformations that is applied to the input set specified by the URI. On the result set of the pipeline, the standard system query options come into effect.

Example ​

GET /Orders(10)/books?
    $apply=filter(year eq 2000)/
           groupby((author/name),aggregate(price with average as avg))/
    orderby(title)/
    top(3)

This request operates on the books of the order with ID 10. First it filters out the books from the year 2000 to an intermediate result set. The intermediate result set is then grouped by author name and the price is averaged. Finally, the result set is sorted by title and only the top 3 entries are retained.

Transformations ​

• ⁽¹⁾ Supported with experimental feature cds.features.odata_new_parser = true

concat ​

The concat transformation applies additional transformation sequences to the input set and concatenates the result:

GET /Books?$apply=
    filter(author/name eq 'Bram Stroker')/
    concat(
        aggregate($count as totalCount),
        groupby((year), aggregate($count as countPerYear)))

This request filters all books, keeping only books by Bram Stroker. From these books, concat calculates (1) the total count of books and (2) the count of books per year. The result is heterogeneous.

The concat transformation must be the last of the apply pipeline. If concat is used, then $apply can't be used in combination with other system query options.

skip, top, and orderby ​

Beyond the standard transformations specified by OData, CDS Java supports the transformations skip, top, and orderby that allow you to sort and paginate an input set:

GET /Order(10)/books?
    $apply=orderby(price desc)/
           top(500)/
           groupby((author/name),aggregate(price with max as maxPrice))

This query groups the 500 most expensive books by author name and determines the price of the most expensive book per author.

Aggregation Methods ​

Custom Aggregates ​

Instead of explicitly using an expression with an aggregation method in the aggregate transformation, the client can use a custom aggregate. A custom aggregate can be considered as a virtual property that aggregates the input set. It's calculated on the server side. The client doesn't know How the custom aggregate is calculated.

They can only be used for the special case when a default aggregation method can be specified declaratively on the server side for a measure.

A custom aggregate is declared in the CDS model as follows:

• The measure must be annotated with an @Aggregation.default annotation that specifies the aggregation method.
• The CDS entity should be annotated with an @Aggregation.CustomAggregate annotation to expose the custom aggregate to the client.

@Aggregation.CustomAggregate#stock : 'Edm.Decimal'
entity Books as projection on bookshop.Books {
  ID,
  title,

  @Aggregation.default: #SUM
  stock
};

With this definition, it's now possible to use the custom aggregate stock in an aggregate transformation:

GET /Books?$apply=aggregate(stock) HTTP/1.1

which is equivalent to:

GET /Books?$apply=aggregate(stock with sum as stock) HTTP/1.1

Currencies and Units of Measure ​

If a property represents a monetary amount, it may have a related property that indicates the amount's currency code. Analogously, a property representing a measured quantity can be related to a unit of measure. To indicate that a property is a currency code or a unit of measure it can be annotated with the Semantics Annotations @Semantics.currencyCode or @Semantics.unitOfMeasure.

@Aggregation.CustomAggregate#amount   : 'Edm.Decimal'
@Aggregation.CustomAggregate#currency : 'Edm.String'
entity Sales {
    key id        : GUID;
        productId : GUID;
        @Semantics.amount.currencyCode: 'currency'
        amount    : Decimal(10,2);
        @Semantics.currencyCode
        currency  : String(3);
}

The CAP Java SDK exposes all properties annotated with @Semantics.currencyCode or @Semantics.unitOfMeasure as a custom aggregate with the property's name that returns:

• The property's value if it's unique within a group of dimensions
• null otherwise

A custom aggregate for a currency code or unit of measure should be also exposed by the @Aggregation.CustomAggregate annotation. Moreover, a property for a monetary amount or a measured quantity should be annotated with @Semantics.amount.currencyCode or @Semantics.quantity.unitOfMeasure to reference the corresponding property that holds the amount's currency code or the quantity's unit of measure, respectively.

Other Features ​

Open Types ​

An entity type or a complex type may be declared as open, allowing clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type. To indicate that the entity or complex type is open, the corresponding type must be annotated with @open:

service CatalogService {
  @open 
  entity Book { 
    key id : Integer; 
  } 
}

The cds build for OData v4 will render the entity type Book in edmx with the OpenType attribute set to true:

<EntityType Name="Book" OpenType="true"> 
  <Key>
    <PropertyRef Name="id"/>
  </Key>
  <Property Name="id" Type="Edm.Integer" Nullable="false"/>
</EntityType>

The entity Book is open, allowing the client to enrich the entity with additional properties, e.g.:

{"id": 1, "title": "Tow Sawyer"}

or

{"title": "Tow Sawyer",
 "author": { "name": "Mark Twain", "age": 74 } }

Open types can also be referenced in non-open types and entities. This, however, doesn't make the referencing entity or type open.

service CatalogService {
  type Order {
    guid: Integer;
    book: Book;
  }

  @open 
  type Book {} 
}

Following payload for Order is allowed:

{"guid": 1, "book": {"id": 2, "title": "Tow Sawyer"}}

Note that type Order itself is not open thus doesn't allow dynamic properties, in contrast to type Book.

Java Type Mapping ​

Simple Types ​

The simple values of deserialized JSON payload can be of type: String, Boolean, Number or simply an Object for null values.

Structured Types ​

The complex and structured types are deserialized to java.util.Map, whereas collections are deserialized to java.util.List.

Singletons ​

A singleton is a special one-element entity introduced in OData V4. It can be addressed directly by its name from the service root without specifying the entity's keys.

Annotate an entity with @odata.singleton or @odata.singleton.nullable, to use it as a singleton within a service, for example:

service Sue {
  @odata.singleton entity MySingleton {
    key id : String; // can be omitted
    prop : String;
    assoc : Association to myEntity;
  }
}

It can also be defined as an ordered SELECT from another entity:

service Sue {
  @odata.singleton entity OldestEmployee as
    select from Employees order by birthyear;
}

Requesting Singletons ​

As mentioned above, singletons are accessed without specifying keys in the request URL. They can contain navigation properties, and other entities can include singletons as their navigation properties as well. The $expand query option is also supported.

GET …/MySingleton
GET …/MySingleton/prop
GET …/MySingleton/assoc
GET …/MySingleton?$expand=assoc

Updating Singletons ​

The following request updates a prop property of a singleton MySingleton:

PATCH/PUT …/MySingleton
{prop: “New value”}

Deleting Singletons ​

A DELETE request to a singleton is possible only if a singleton is annotated with @odata.singleton.nullable. An attempt to delete a singleton annotated with @odata.singleton will result in an error.

Creating Singletons ​

Since singletons represent a one-element entity, a POST request is not supported.

V2 Support ​

While CAP defaults to OData V4, the latest protocol version, some projects need to fallback to OData V2, for example, to keep using existing V2-based UIs.

Enabling OData V2 via Proxy in Node.js Apps ​

CAP Node.js supports serving the OData V2 protocol through the OData V2 adapter for CDS, which translates between the OData V2 and V4 protocols.

For Node.js projects, add the proxy as express.js middleware as follows:

1. Add the adapter package to your project:

   sh

   npm add @cap-js-community/odata-v2-adapter

2. Add this as a plugin to your project:

   package.json.cdsrc.json

   json

   {...
   "cds" {
     "cov2ap" : {
       "plugin" : true
       }
     }
   }

   json

   {
   "cov2ap" : {
     "plugin" : true
     }
   }

3. Access OData V2 services at http://localhost:4004/v2/${path}.

4. Access OData V4 services at http://localhost:4004/${path} (as before).

Example: Read service metadata for CatalogService:

• CDS:

  cds

  @path:'/browse'
  service CatalogService { ... }

• OData V2: GET http://localhost:4004/v2/browse/$metadata

• OData V4: GET http://localhost:4004/browse/$metadata

Find detailed instructions at @cap-js-community/odata-v2-adapter.

Using OData V2 in Java Apps ​

In CAP Java, serving the OData V2 protocol is supported natively by the CDS OData V2 Adapter.

Miscellaneous ​

Omitting Elements from APIs ​

Add annotation @cds.api.ignore to suppress unwanted entity fields (for example, foreign-key fields) in APIs exposed from this the CDS model, that is, OData or OpenAPI. For example:

entity Books { ...
  @cds.api.ignore
  author : Association to Authors;
}

Please note that @cds.api.ignore is effective on regular elements that are rendered as Edm.Property only. The annotation doesn't suppress an Edm.NavigationProperty which is rendered for associations or compositions. If a managed association is annotated, the annotations are propagated to the (generated) foreign keys. In the previous example, the foreign keys of the managed association author are muted in the API.

Absolute Context URL ​

In some scenarios, an absolute context URL is needed. In the Node.js runtime, this can be achieved through configuration cds.odata.contextAbsoluteUrl.

You can use your own URL (including a protocol and a service path), for example:

cds.odata.contextAbsoluteUrl = "https://your.domain.com/yourService"

to customize the annotation as follows:

{
  "@odata.context":"https://your.domain.com/yourService/$metadata#Books(title,author,ID)",
  "value":[
    {"ID": 201,"title": "Wuthering Heights","author": "Emily Brontë"},
    {"ID": 207,"title": "Jane Eyre","author": "Charlotte Brontë"},
    {"ID": 251,"title": "The Raven","author": "Edgar Allen Poe"}
  ]
}

If contextAbsoluteUrl is set to something truthy that doesn't match http(s)://*, an absolute path is constructed based on the environment of the application on a best effort basis.

Note that we encourage you to stay with the default relative format, if possible, as it's proxy safe.