Skip to content

Changing enumeration attributes, restructure page #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sbont wants to merge 2 commits into
base: publish-enums
Choose a base branch
from
Open

Changing enumeration attributes, restructure page #23

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
889ed95
Changing enumeration attributes
sbont Feb 8, 2023
8965662
restructure
sbont Feb 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 48 additions & 29 deletions ...hed-odata-services/odata-query-options.md → ...lished-odata-services/odata-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
---
title: "OData Query Options"
url: /refguide/odata-query-options/
title: "OData Operations"
url: /refguide/odata-operations/
Copy link
Owner

@joostverhoog joostverhoog Feb 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a procedure for moving pages to prevent 404 for existing links.

Copy link
Collaborator Author

@sbont sbont Feb 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At second thought, "OData operations" can also be confusing, as it is also the umbrella term for OData actions and functions. "Working with OData", maybe?

Copy link
Owner

@joostverhoog joostverhoog Feb 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "OData Query Options" is not too bad. It's about the options that clients have when querying this OData service.

tags: ["OData", "filter", "count", "sort", "select", "page", "studio pro"]
---

## 1 Introduction
## 1 Reading objects

This is a list of query options for OData.
### 1.1 Retrieving Objects

This section contains of available query options for OData.

{{% alert color="info" %}}
We currently only support the options described here.
{{% /alert %}}

## 2 Retrieving Objects

### 2.1 Retrieving All Objects
#### 1.1.1 Retrieving All Objects

All objects can be retrieved by specifying the URI. For example: `/odata/myservice/v1/Employees`. You can see this if you specify the URI in a browser.

### 2.2 Retrieving a Single Object
#### 1.1.2 Retrieving a Single Object

A single object can be retrieved by passing the object identifier in the URI. For example: `/odata/myservice/v1/Employees(8444249301330581)`.

### 2.3 Retrieving Associated Objects
#### 1.1.3 Retrieving Associated Objects

For this example, imagine that you have four entities in your domain model: **Employee**, **Car**, **Address**, and **City**. They include the following:

Expand All @@ -32,23 +32,23 @@ For this example, imagine that you have four entities in your domain model: **Em

Associated objects can be retrieved by passing the `$expand` query parameter. For example: `/odata/myservice/v1/Employees?$expand=Cars,Address($expand=City)` (OData 4) or `/odata/myservice/v1/Employees?$expand=Cars,Address/City` (OData 3).

## 3 Counting the Number of Objects
### 1.2 Counting the Number of Objects

### 3.1 Retrieving a Count of Objects
#### 1.2.1 Retrieving a Count of Objects

You can find out how many objects there are by passing the `$count` query option. In this case, the result is an integer which is the number of objects. For example: `/odata/myservice/v1/Employees/$count`.

### 3.2 (Inline) Count
#### 1.2.2 (Inline) Count

For OData 4, by setting the `$count` query option to `true`, a count of the number of items returned will be included in the result. For example: `?$count=true`.

For OData 3, by setting the `$inlinecount` query option to `allpages`, a count of the number of items returned will be included in the result. For example: `?$inlinecount=allpages`.

## 4 Filtering
### 1.3 Filtering

Filters are applied by appending a `$filter=...` parameter to the request. For example: `/Employees?$filter=Name eq 'John'`.

### 4.1 Passing attributes
#### 1.3.1 Passing attributes

This table describes how to pass values for different attribute types:

Expand All @@ -59,7 +59,7 @@ This table describes how to pass values for different attribute types:
| Datetime | For OData 4: a plain value (for example, `2021-12-31`). For OData 3: Preceded with `datetime` and enclosed in single quotes (for example, `datetime'2021-12-31'` or `datetime'<epoch value here>'`) |
| Other | Plain value (for example, 15) |

### 4.2 Comparison Operators
#### 1.3.2 Comparison Operators

We support the following comparison operators:

Expand All @@ -72,7 +72,7 @@ We support the following comparison operators:
| ge | greater than or equal to | `/Employees?$filter=Age ge 15` |
| le | less than or equal to | `/Employees?$filter=Age le 15` |

### 4.3 Arithmetic Operators
#### 1.3.3 Arithmetic Operators

| Operator | Meaning | Example | Returns |
| --- | --- | --- | --- |
Expand All @@ -82,7 +82,7 @@ We support the following comparison operators:
| div | divided by |`/Products?$filter=Prices div 2 eq 10` | All products with price 20 |
| mod | modulus |`/Products?$filter=Prices mod 5 eq 0` | All products with price divisible by 5 |

### 4.4 Functions
#### 1.3.4 Functions

| Function | Example | Returns |
| --- | --- | --- |
Expand All @@ -99,7 +99,7 @@ We support the following comparison operators:

<small><sup>1</sup> In OData 3, the `contains` function is called `substringof`, and its arguments are reversed For example, `/Employees?$filter=substringof('f', Name)`</small>

### 4.5 Combining Filters
#### 1.3.5 Combining Filters

Filters can be combined with `and`, `or`, `not`, and `()`. For example: `?$filter=Name eq 'John' and (Age gt 65 or Age lt 11)`.

Expand All @@ -110,7 +110,7 @@ Filters can be combined with `and`, `or`, `not`, and `()`. For example: `?$filte
| not | `/Employees?$filter=not(Name eq 'John')` |
| ( ) | `/Employees?$filter=Name eq 'John' and (Age gt 65 or Age lt 11)` |

### 4.6 Filtering by Association
#### 1.3.6 Filtering by Association

You can filter on attributes of an associated entity. The way you do this depends on whether the association exposes one object or a list of objects.

Expand All @@ -121,7 +121,7 @@ You can filter on attributes of an associated entity. The way you do this depend

Filtering on an associated object or list in this way is possible when you [expose associations as a link](/refguide/odata-representation/#associations). It is not possible when you [expose associations as an associated object ID](/refguide/odata-representation/#associations).

## 5 Sorting
### 1.4 Sorting

You can sort the result using the `$orderby` query option. For example: `?$orderby=Name` or `?$orderby=BirthPlace/CityName`.

Expand All @@ -131,37 +131,39 @@ You can also order the result in a descending direction. For example: `?$orderby

It is possible to sort on multiple attributes, which have to be comma-separated. For example: `?$orderby=Name asc,Age desc`.

## 6 Selecting fields
### 1.5 Selecting fields

You can select which attributes and associations to return by specifying the `$select` query option. For example: `?$select=Name,Age`.

## 7 Paging {#paging}
### 1.6 Paging {#paging}

### 7.1 Top (Limit)
#### 1.6.1 Top (Limit)

You can limit the number of returned objects using the `$top` query option, where the limit is a positive integer. For example: `?$top=100`.

### 7.2 Skip (Offset)
#### 1.6.2 Skip (Offset)

You can skip a number of objects before retrieving the result using the `$skip` query option, where the offset is a positive integer. For example: `?$skip=100` will return objects starting with the 101st object in the list.

## 8 Null Literals
### 1.7 Null Literals

You can compare values against the `null` literal. For example: `?$filter=Name eq null`.

In this example, `Name` is a string attribute that can have no assigned value in the database. Note that `null` means *no value* as opposed to `''` (which is an empty string).

When you filter against associations, null literals can be quite useful. For example: `?$filter=Association_A_B ne null`. In this example, you query for objects of entity type `A` that have at least one association set to objects of entity type `B`.

## 9 Passing Query Options in the Request Body
### 1.8 Passing Query Options in the Request Body

If the OData query is too long to be sent as a `GET` request, clients can send the query as a `POST` request to the `/$query` endpoint. For example, `GET /Products?$select=Name,Price` and `POST /Products/$query` with `$select=Name,Price` in the request body give the same result. These `POST` requests must specify the header `Content-Type: text/plain`.

{{% alert color="info" %}}
The body must adhere to *URL encoding* principles. So, for instance, spaces, tabs, and newlines are not allowed.
{{% /alert %}}

## 10 Updating Objects {#updating-objects}
## 2 Updating Objects {#updating-objects}

### 2.1 Updating attributes

When a published resource has the [Updatable](/refguide/published-odata-resource/#capabilities) capability, clients can update its attributes and associations by sending a `PATCH` request to the URL of the object (for example, `PATCH /odata/myservice/v1/Employees(8444249301330581)`).

Expand All @@ -175,6 +177,23 @@ Specify new values for attributes in the body of the request. Here is an example
}
```

### 2.1.1 Updating enumerations

Attributes of an enumeration type can be updated by specifying the exposed value of the enumeration, without the prefix of the enumeration type, in the body of the `PATCH` request.
For an attribute of type `Country` with values `MyModule.Country.FR`, `MyModule.Country.BR` and `MyModule.Country.JP`, exposed as `France`, `Brazil`, and `Japan` respectively, you can update your object as follows:

```json
{
"Country": "Brazil"
}
```

{{% alert color="info" %}}
Specifying the enumeration member by its numeric value is not supported.
{{% /alert %}}

### 2.2 Updating asociations

When the association refers to a single object, use the `@id` syntax to set an associated object, or use `null` to empty the associated object. Here is an example:

```json
Expand Down Expand Up @@ -208,7 +227,7 @@ Clients can only update an association from the entity that is the [owner](/refg
The *updating attributes* functionality was introduced in Studio Pro [9.6.0](/releasenotes/studio-pro/9.6/). The *updating associations* functionality was introduced in Studio Pro [9.8.0](/releasenotes/studio-pro/9.8/).
{{% /alert %}}

## 10 Inserting Objects {#inserting-objects}
## 3 Inserting Objects {#inserting-objects}

When a published resource has the [Insertable](/refguide/published-odata-resource/#capabilities) capability, clients can create new objects by sending a `POST` request to the URL of the entity set (for example, `POST /odata/myservice/v1/Employees`).

Expand All @@ -229,7 +248,7 @@ Clients can only set values for an association from the entity that is the [owne
The *inserting objects* functionality was introduced in Studio Pro [9.12.0](/releasenotes/studio-pro/9.12/).
{{% /alert %}}

## 11 Deleting Objects {#deleting-objects}
## 4 Deleting Objects {#deleting-objects}

When a published resource has the [Deletable](/refguide/published-odata-resource/#capabilities) capability, clients can delete an object by sending a `DELETE` request to the URL of the object (for example, `PATCH /odata/myservice/v1/Employees(8444249301330581)`).

Expand Down