Analyzing EC OData API Performance

OData API supports on some http operations like GET, POST, PUT, PATCH and DELETE, we use the basic operations to get or edit the entities like User, PerPerson, picklist and so on in EC

HTTP Operations

• GET: Query
• POST: Create
• PUT: Update
• PATCH: Partial Update
• DELETE: Delete

HTTP Resources or Services

• User, PerPerson, Picklist, Position

HTTP Parameter

• Separated by "?" (first one after Resource) and "&" characters
• OData standard parameters are starting with an "$" character, like $filter or $select

XML Definition of API metadata

• Can be retrieved via OData API $metadata call an result can be imported after download into Excel:

In order to get extra information, such as language labels, picklists, beyond what the standard OData metadata provides, SAP Successfactors OData exposes metadata as an entity. The SAP SuccessFactors OData API exposes an entity named 'Entity'. Its properties are exposed as complex type value embedded in the response body of 'Entity'. Different forms of metadata can thus be exposed without changing the standard OData metadata format. You can access the new metadata just like you would access a regular entity. In addition, it supports a simple filter to output metadata of a specific entity.

The metadata can be achieved via OData API by $metadata in the https call. You can request for the metadata via Firefox Rest Client. Because the data is a little large for the metadata, the request may takes more time.

Select the play button to learn about the $format parameter.

Filter options and parameters

The below example shows an OData API query example using filter and select. For the filter we can give a specified value to a field to query on the corresponding entity. For the select we can also define the fields to return the response.

• $filter=personIdExternal%20eq%20’greinhard’

  • %20 is special escape character for space; like %28 and %29 is for brackets like "(" and ")"

  • Available operators are EQ,NE,GT,GE,LT,GT and those can be combined with NOT, AND and OR

• $select=firstName defines fields to be returned separated by spaces

The below example shows how to use the parameter of expand. Expand always used to navigate to other entity.

Expanding the data – navigating the data model

• $expand=personNav
• $select=firstName,personNav

  • expands firstName in root resource and all fields in navigated resource person

• $select=firstName,personNav/dateOfBirth

  • expands firstName in root resource and all fields in navigated resource person

The above example shows us how to use the parameter of $expand and $filter

The response identifies a set of User Entities whose personNav/emailNav property is emailAddress which is equal to gerald.reinhard@sap.com, After the entities are retrieved, the response removes unselected columns. Then the $expand option expands the selected columns that is a navigation property

Deep Filtering using $filter and $expand

• $expand performed after filter independent from each other (see result next slide)
• $select not required for filtered attributes

Filter+Expand

• Filter applied to root resource
• Expand applied to filtered root resource
• Result: Expanded Email not matching the filter

The below content describes how to query effective-dated entities, to use fromDate and toDate will return all historic data of root entity in the response. But if the root entity is not effective date, the fromDate and toDate will be applied to the next effective dated entity in the navigation hierarchy, and all of the effective dated records falling into the time interval between fromDate and toDate will be returned.

Also If historic data of an effective dated record is returned and a navigation/expand from those records to another effective dated record is done the start date of the first effective dated entity will be used to filter the 2nd one.

• For effective dated entities to tell the API to return all historic data of the root entity in the response.
• If the root entity is not effective dated toDate and fromDate will be applied to the next effectived dated entity in the navigation hierarchy:
  • https://salesdemo4.successfactors.com:443/odata/v2/PerPerson? $filter=employmentNav/jobInfoNav/userId%20eq%20'greinhard‘ &fromDate=1900-01-01 &$select=employmentNav/jobInfoNav/startDate,employmentNav/jobInfoNav/departmentNav/externalCode &$expand=employmentNav/jobInfoNav/departmentNav
• All effective dated records falling into time interval between fromDate and toDate will be returned.

• If historic data of a effecitve dated record is returned and a navigation/expand from those records to another effective dated record is done the start date of the first effective dated entity will be used to filter the 2nd one.
  • https://salesdemo4.successfactors.com:443/odata/v2/EmpJob? $filter=userId%20eq%20'greinhard'&fromDate=1900-01-01 &$select=startDate,departmentNav/externalCode &$expand=departmentNav

This describes how to query effective-dated entities, to use fromDate and toDate will return all historic data of root entity in the response. But if the root entity is not effective date, the fromDate and toDate will be applied to the next effective dated entity in the navigation hierarchy, and all of the effective dated records falling into the time interval between fromDate and toDate will be returned.

Also If historic data of an effective dated record is returned and a navigation/expand from those records to another effective dated record is done the start date of the first effective dated entity will be used to filter the 2nd one

• Partial Deletions not supported for non effective dated entities such as by PerEmail, PerPhone
• Full deletion not supported by any API yet
• lastModifiedOn (server timezone) lastModifiedDateTime (UTC)

• The OData API provides several pagination options for query results.
• A single OData HTTP GET request can return at most 1,000 records. This is reasonable because most HTTP clients have a timeout limit of 2 - 5 minutes.
• A request running longer than the limit gets an HTTP timeout error. Therefore, it is often required to tune complex queries and lower the data size for them to complete within the timeout restriction.

The customer can choose between two types of Pagination:

• Client Pagination
• Server Pagination

• Client Pagination is the most fundamental pagination mechanism. It uses query options on the client side to create an "offset" that restricts the amount of data returned from the server. A client uses the following URI parameter.
• A client uses the following URI parameter:
  • The $top parameter indicates the number of records to return in the batch. The default and the maximum number is 1,000 records.
  • The $skip parameter indicates the number of records in the full data set to skip before fetching data.
• For example, a query with $skip=2000&$top=500 returns the 5th page of data where the page size is 500.

• Unlike client pagination, where the pagination is controlled by client specified parameters, server pagination is controlled on the server side.
• There are two types of server pagination: cursor-based pagination and snapshot-based pagination. Both types of pagination return a "__next" parameter at the end of each query response that contains a $skiptoken value indicating the next page of data.
• Cursor-based pagination maintains a database "cursor" on the server throughout pagination HTTP requests. The cursor represents a pointer to the start of the next page in the full data set. This is enabled using the &paging=cursor URI parameter.
• Snapshot pagination works by persisting a list of all business keys of the data set on the server. This is enabled using the &paging=snapshot URI parameter.

When to use the different types of pagination:

• For UI consumption, use client offset pagination. This is the only supported method on UI.
• Cursor-based pagination and snapshot-based pagination are recommended for integration use cases.
• We recommend that you tune your queries when you use snapshot-based pagination. If you have problems with first page performance for extremely large data sets, switch to cursor-based pagination if applicable.

And last but not least, we have optimized the OData entities FOLocation and FOPayGrade for snapshot-based pagination to improve performance.