Docs‎ > ‎

Welcome Walk-through

This page introduces the key concepts of API Creator and explains how to use the samples to see the key concepts. You can view additional training resources Getting Started.

Prerequisites: Before you start, complete the following:
  • Explore the Welcome Window and the Architecture for suggestions on getting started.
  • View the Getting Started videos.
  • Take the tour (it starts automatically in API Creator), which creates your first API using Northwind.

API Creation

The tour uses Northwind to illustrate how to create APIs, with default resources for each table, view, and stored procedure. You can change the API style (API Properties, Settings, Default Response Format).

REST Lab

API creation invokes the REST Lab to confirm your API is operational. Use it to query and update data. Explore its services for filter, sort, etc. Observe pagination of large results and optimistic locking.

Stored Procedures

API Creation creates stored procedures as endpoints. The JavaDB database does not support these, so they are not provided in the jetty-based WAR file, but you can test them:
  • Northwind MySQL - Select Procedure, CustOrdersDetail and append the following to the URL: 
    ?arg.OrderID=10248
  • Demo MySQL - Select Procedure > get_employee and append the following to the URL: 
    ?arg.given_employee_id=1&arg.plus_one=1

Swagger Documentation

View code samples, including automatically-created Swagger documentation.

Custom Resources

The tour shows you how to define custom resource types. Observe there was no code generation, deployment, etc. View the Demo API and explore the CustomerBusinessObject. Run it in the REST Lab.

For more information about defining custom resource types, see Define Custom REST Resources.

Free SQL Resource Types

While SQL is ordinarily automated, you can provide your own SQL when necessary using Free SQL Resource Type. In the Demo API, select Resources, PurchaseOrdersFreeSQL, Details. The Details tab contains custom SQL.

For more information about defining Free SQL resource types, see Define Free SQL Resource Types

JavaScript Resource Types

You can materialize resource responses with JavaScript Resource Type. In the Demo API, click CustomerJSOrdersRest resource, OrdersRest sub-resource, Details. View the JavaScript in the the Details pane. Explore JavaScriptMongo, which is the root resource by way of JavaScript that makes direct calls to Mongo APIs.

MongoDB Resource Types

You can create resources that map to MongoDB resources:
  • CustomerJoinMongoPurchaseOrders (sub resource by way of JavaScript).
  • zipcodes
Note: The Jetty package does not presume web connectivity, so these are not available in that package.

Custom Endpoints

You can create ad hoc endpoints using HTTP Handlers. Create a sample endpoint by clicking Custom Endpoints. Such resource do not enforce security.

Integrate

APIs can integrate databases into a single API, and inter-operate with other systems.

Multiple Data Sources: SQL

Explore Resources, MDBDemoCustomers. Customers come from Demo, Orders from Sample.
Note: These can be different database types.

Multiple Data Sources: Non SQL

The previous examples illustrated integration:
  • CustomerJSOrdersRest illustrates integrating SQL and external RESTful data.
  • CustomerJoinMongoPurchaseOrder integrates SQL and NoSQL data into one nested resource.

Systems Integration

Switch to the Sample API. Explore this as described here.

Data Explorer

Switch back to the Demo API. Go to Data Explorer and experiment with filtering, sorting, updates, and lookups. Customize with Author Mode.

For more information about Data Explorer, see Data Explorer.

Manage

Manage your business policy for logic and security, using rules, JavaScript, and point/click forms.

Rules - Reactive Logic

Ensure database integrity with a combination of server-side JavaScript events and reactive logic.

For more information about rules, see Specify your Business Rules.

JavaScript Events

Click Rules, Event: Audit Purchase Order. This event coded with server-side JavaScript. Key points:
  1. Your object model is created for you, as used in the first line (row.amount_total != oldRow.amount_total).
  2. Contextual variables are passed to you.
    For more information about the JavaScript contextual variables, see Quick Reference.
  3. Build code using the Expression Help.
The Send Mail example illustrates calling your own loadable Java/JavaScript libraries (Clear the Short Menus checkbox, then click API Properties, Libraries).

Reactive Logic

Save time by using Reactive Logic:
  1. See the Reactive Logic for this topic (requirement) by clicking Rules, Check Credit.
  2. For more background , click Edit Topic.
You can define topics (API Properties, Topics). Topics can include rich text links, such as to a Requirements Management system.

Security

You can assign a Pluggable Authentication Provider in API Properties, Details. While not used in the Demo API, you can explore this in the Business to Business Sample.

In Demo, you can explore Role-based control over which resources a Role can access, and which rows are returned. You can explore security in the following ways:
  • Use the Rest Lab with Auth Token SalesRep, and observe "no such resource" on GET to PurchaseOrders.

  • Use Security, Sales Rep, REST endpoints to authorize access to PurchaseOrders (steps 1-2-3 in the diagram - click the thumbnail for the image).

  • Return to the Rest Lab, and verify you can GET PurchaseOrders. Note the number of lines of output.
  • Use Auth Token Broad Access. Get, and observe that more data is retrieved
    • This illustrates Row Level Security: different rows are returned based on the users set of Roles.
Such security can involve the use of Global rows/variables. Navigate to Security, Sales Rep, Permissions (click the thumbnail for the image). @{current_employee_row.employee_id}current_employee_row is defined on the Globals tab.

For more information about security, see the Authentication.

Dev

Debugging

Use Data Explorer (or REST Lab) to alter a Lineitem quantity, and examine the Logs to observe the effect on related objects. The log shows every SQL, and every rule (including row state), with indention for multi-table chaining.

Export

You can create versions of your API by exporting them (API Properties, Export). You can import them from the Home page; ensure you update their settings. This is a good way to move APIs from dev to pre-production to production, source control them, etc.

Next Steps

Create your own API

After you have completed the steps above, get started by creating a new API, which contains your resources, logic, and security. First, connect to a database. The database can be one of the following:
    • An existing database, in the cloud or on-premises.
    • A new database you create using your existing tools and procedures or the database API Creator creates automatically.

Advanced Example

You can extend Northwind to illustrate the Business To Business integration. The Business To Business integration illustrates several useful Live API Creator concepts that can be helpful in real-world projects.