Understanding OData

http://www.odata.org/getting-started/understand-odata-in-6-steps/

OData (Open Data Protocol) is a standard that defines the best practice for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats and query options etc. OData also guides you about tracking changes, defining functions/actions for reusable procedures, and sending asynchronous/batch requests etc. Additionally, OData provides facility for extension to fulfil any custom needs of your RESTful APIs.

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools. Some of them can help you interact with OData even without knowing anything about the protocol. 

To learn more about the OData query syntax, see http://www.OData.org/ and look for "Basic Tutorial” and "Advanced Tutorial”.

alert

Important

OData calls must be made from within Forms Builder or Workflow.
OData calls via ApiProxy outside of Forms Builder or Workflow are not supported.   

Data Model

The Anthology data model is based on the Command Query Responsibility Segregation (CQRS) pattern. As such, it provides a Query Model and a Command Model.

Command ands Query Model

The classes in the following namespaces (assemblies) represent the Command Model interfaces:

  • Cmc.Nexus.Academics
  • Cmc.Nexus.Admissions
  • Cmc.Nexus.CareerServices
  • Cmc.Nexus.Common
  • Cmc.Nexus.FinancialAid
  • Cmc.Nexus.StudentAccounts
  • Cmc.Nexus.StudentServices

Command Model

The Command Model is optimized to handle transactions and calculations. Most of the business and decision logic resides in the assemblies listed above.

The Command Model is exposed to the web client through WebAPI Controllers. Unlike the query model, the Command Model's relationships only include the data that will be updated in a single transaction. An example of a transaction sequence is the CreateTask command shown below.

Command Model

Query Model

The Query Model shows the relationships between the Anthology Student data. The classes in the Cmc.Nexus.Models namespace (assembly) represent the Query Model interfaces. The entity properties of these classes are exposed to the client through OData Controllers. This enables users to navigate through all the relationships in the data model using OData queries as shown in the sequence diagram below.

Query Model

OData Queries

Forms Builder supports list controls such as Drop-down, Multiselect, and Typeahead. Each list control has a Lookup Query property that is used to retrieve specific values from the database. Lookup Queries are specified as OData queries.

The data model provides a query model and a command model. For the purposes of constructing OData queries, refer to the query model. The query model is available at the following URL:

<Base URL>/ds/metadata/ModelMetadata/GetFullModel

Where <Base URL> is the Student Base URL displayed in the About Forms Builder window:

About Forms Builder

In this example, the query model is available at:

http://student.nexus-02/ds/metadata/ModelMetadata/GetFullModel

Query the data model (http://student.nexus-02/ds/metadata/ModelMetadata/GetFullModel). Search the metadata for the entity you are working, e.g., EntityType Name="Student". The metadata for the "Student" entity provides several prebuilt OData queries.

Note: All pre-built queries contain "select" options for the Code, Name, and Id columns and are ordered by Name.

OData Query

Access the Student Base URL in a browser. In our example, the Student Base URL is as follows with /ds/campusnexus/$metadata appended to the end of the URL to view the metadata values:

http://student.nexus-02/ds/campusnexus/$metadata

Metadata

Rest APIs - Swagger

You can access the Swagger UI for the REST APIs for the Web Client of Anthology Student version 19.0 and later using the following steps:

  1. Launch Anthology Student in a browser.

  2. Log in using administrator-level credentials. If you do not have administrator credentials, see the Note below.

  3. Right-click the tab within your browser, and select Duplicate Tab.

  4. Replace #/home at the end of the URL with swagger/ui and hit Enter. The Swagger UI will load.

    Swagger UI

  5. Select a specification from the drop-down list in the header bar and expand the list of entities and methods.

    If you are unsure where the entity you wish to work with resides, refer to Cmc.Nexus.Models in Workflow Help.

  6. Use the Try it out option in the Swagger UI to test sample values, commands, or models.

  7. Use Command Model specifications to leverage the logic behind the REST APIs. Use Query Model specifications to query the OData Model.

Note: If you have not logged in using an administrator account or someone provisioned your account to use the APIs, use the following steps to authorize a user to leverage the REST API logic.

  1. On the Server that is hosting the CMCStudentWebClient, open the web.config file and search for the key="apiKey".

  2. Double-click or highlight the content of the apiKey value (e.g., "c9tZIhnBgJugdL8H8YVlRJzFkXGSrY6Lk2HCYs4JVcbIjdbUC3SIpNxOJPkZo8qG") to copy it.

  3. On the REST API page, click Authorize, paste your value into the Value: field, and click the Authorize button.