How to Configure OData Endpoint
An OData endpoint can be created using the +NEW menu, as any other object. You can create an OData endpoint for your data source in just three simple steps:
- Select a connection to your data source.
- Drag its tables you want to publish data from to the endpoint diagram.
- Specify the endpoint name and click the Create button.
If you want to limit access to your endpoint, you may also tweak endpoint security settings and other settings. You can also optionally tweak entity and property naming, exclude some source fields from the endpoint, and customize associations between entities.
Selecting Data to Publish
When creating OData endpoint, the first step is selecting a connection to your data source. You can either select an existing connection, or create a new one.
After this the endpoint editor opens. Its left part displays the data source tables/objects, and the right part displays the diagram with objects added to endpoint. To add an object to endpoint, simply drag it to the diagram.
When you drag a table to the diagram, Skyvia automatically creates the corresponding entity set and entity type. Skyvia also automatically creates relationships (associations) with other entity types on the diagram, corresponding to tables, with which there are relationships in the data source. If a table references itself in the data source, Skyvia creates a self-referencing association on the diagram. By default, Skyvia exposes all the table fields via the OData protocol. However, you can double-click entities on the diagram and tweak them in more details, if necessary.
OData entities on the diagram are presented as rounded rectangle shapes on the diagram, which consist of a header, a list of entity fields, and a list of navigation properties. Properties that are an entity key, have a key icon on the left.
To edit an entity, click the Edit Entity button in the entity header. This will open the Edit Entity dialog box, displaying entity naming parameters and a table with entity fields with the information about them.
To delete an entity, click the Delete Entity button in the entity header.
Entity and Property Naming
By default, the entity name is generated based on the source table/object name. If the source table/object name is a plural form, it is singularized. The entity set name is generated by pluralizing the source table/object name if necessary. If the source table/object name contains characters, not allowed in names by OData standard, they are omitted. If the generated name coincides with an OData keyword, underscore characters are added on both sides of the name.
If the default names don’t suite you, you can edit the generated Entity Name and Entity Set Name in the Edit Entity dialog box. Yo can also specify the data source table to expose data from via this entity in the Source box.
Property names are also generated by removing characters, not allowed in names by OData standard, from the underlying column/field names. You can view the source column/field names in the Source column of the grid. If necessary, you may edit the generated property names in the Name columns.
This can be useful, for example, if the source has too long field names, and you want to create an OData endpoint for linking the source to Salesforce Connect. Salesforce Connect truncates property names over 50 characters, and sometimes this may lead to errors when two property names in the same entity are truncated to the same 50-character string.
Entity key is a set of properties, uniquely identifying an entity instance. Each entity must have an entity key. By default, it is generated from the primary key of the underlying database table, or id field of the underlying cloud object. The Edit Entity dialog box displays properties, included to entity key, with a key icon in the Key column.
However, you may need to generate an OData entity from a database view or a BigQuery table, which does not have a primary key. If necessary, you may customize (or create) an entity key manually. Just click the Key column for the necessary entity properties to toggle their key status.
Please note that we don’t check if the custom key you define is truly unique and non-nullable. If you customize an entity key, you should care about this yourself. Using a non-unique or nullable entity key may lead to errors when working with the endpoint data. For example, if you request an entity by an entity key value, and this value is not unique in the data source, you will get the “Operation is not valid due to the current state of the object.” error.
Excluding Source Fields from OData Endpoint
If you don’t want some source fields to be available via your OData endpoint, you can easily hide them in the Edit Entity dialog box. For this, select properties that you want to hide by clicking them and using Ctrl or Shift keys and click Hide. To add a hidden field back to the entity as a property, select it and click Show.
If you hide a non-nullable source field, which does not have a default value, and its value is not autogenerated in the source, you won’t be able to add new records to this entity via this endpoint.
When dragging tables to an endpoint diagram, Skyvia automatically generates the corresponding OData entities and relationships (associations) between them, based on the data source metadata. They are displayed as dark blue lines on the diagram. Skyvia even supports self-referencing relationships, when an entity references itself.
For each relation, a navigation property is generated on each side of the relation. Navigation property names are either generated from a foreign key or foreign key field name in the data source, if possible, or simply from the related entity name. These names are then used in OData request URLs when selecting entities by relations.
If necessary, you can edit or delete the generated relationships or even create your own custom ones.
To edit an association, in an entity on any end of the association click Edit Association. The Edit Association dialog box opens.
In this dialog box you can set Names for the corresponding navigation properties on both ends of the association. If needed, you can also select entity columns, on which the association is built, and specify the relation Cardinality — One to Many, One to One, One or Zero to One.
Adding Custom Associations
In addition to associations, automatically generated based on data source metadata, Skyvia allows adding custom associations to OData endpoints.
To add a custom association, find the plus icon at the bottom of the entity that should become the parent in the new association. Drag this icon to the entity, that should become the child in this association. This opens the Edit Association dialog box.
In this dialog box, select the association Cardinality, specify the Names of the corresponding navigation properties, and select the data source Columns, based on which the association will be built.
Please note that in case of custom or modified relationships, you should care about the relation integrity of the data in your data source yourself.
Endpoint Settings: Security, OData Version, Write Access
Using the endpoint editor toolbar, you can change certain endpoint settings. First, you can add user accounts with passwords to make your endpoint data available only for authenticated users. You can also allow access to your endpoint only for specific IP addresses. Check Security Settings for more information.
Additionally, you may select the main OData protocol version for the endpoint in the drop-down list on the toolbar. The following versions are available:
- oData Last - the latest supported version is used. Currently this is OData v4.
- oData v4 - OData v4 is used. It uses JSON format for returned data and metadata.
- oData v1-v3 - OData v3 (backward compatible with OData v1) is used. By default, it uses ATOM format for returned data and metadata.
Please note that regardless of the selected version, Skyvia creates both OData v1-v3 and OData v4 endpoints, which are available by adding odata3/ or odata4/ to the result endpoint URL. The selected version is just a default version, available via base endpoint URL without adding version to it.
By default, Skyvia creates an endpoint with read/write access to data. Of course data can be actually written via this endpoint only if the underlying data source allows writing into the corresponding tables/objects. You can optionally forbid writing to an endpoint by selecting the Read Only check box on the toolbar.
After you finished configuring your endpoint, click Create. The endpoint is immediately created, and the toolbar now displays the following three tabs: Overview, Model, and Log.
Using Created Endpoint
The Overview tab displays basic endpoint information (endpoint connection, numbers of endpoint users and IP address ranges) and the result endpoint URL. This URL leads to the OData endpoint with the selected version of OData protocol. You can also access the endpoint via specific OData protocol version by adding odata3/ or odata4/ to the result endpoint URL.
If your endpoint is valid, and it does not use features, not available in your Connect pricing plan, it is activated immediately, and you can copy and use the endpoint URL in your OData consumer applications. Whenever necessary, you may change the status of your endpoint to Inactive or back to Active in the endpoint title bar or via the corresponding quick action button in the object list.
However, you can save an endpoint even if it is invalid (for example, does not have any entity). Such endpoint is considered a draft endpoint. If your endpoint is invalid (is a draft) or uses features, not available in your pricing plan, it is created inactive, and it cannot be activated till you fix it (for a draft endpoint) or upgrade your connect subscription to a plan, which includes the necessary features.
Editing Created Endpoint
The Model tab allows you to edit the endpoint whenever necessary. You can add or remove entities from the diagram, configure them, edit associations between them, modify endpoint settings - just like when creating a new endpoint. The changes are immediately applied when you click the Save button on the toolbar.
Monitoring Endpoint Activity
The Log tab allows you to monitor all the data access via the endpoint. Check the Monitoring Endpoint Activity topic for more details.