Docs‎ > ‎

Welcome Walk-through

This page introduces the key concepts of API Creator. As recommended on the Welcome screen, before you start, complete the following:
  • Explore the Welcome Page for suggestions on getting started, and the Architectural Overview. The Welcome Page video closely resembles this page.
  • View the Getting Started videos.
  • Take the tour (it starts automatically), which creates your first API using Northwind.
This page explains how to use the samples to see the key concepts. View additional training resources here or from the Training menu in the navigation bar to the left.

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 (disable Short Menus, 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

Stored procedures are also created as end points. The JavaDB database does not support these, so they are not provided in the jetty-based war, but you can test them:
  • Northwind MySQL - Select Procedure > CustOrdersDetail - append the following to the UR: 
          ?arg.OrderID=10248
  • Demo MySQL - Select Procedure > get_employee  - 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 (Execute > API Docs).
Note: You can use Swagger-based tools to create client code (SDKs) to make RESTful data easy to consume in your application (e.g., Java POJOs, or .NET POCOs).

Custom Resources

The tour shows you how to create Custom Resources. Observe there was no code generation, deployment, etc.

Switch to the Demo API, and explore the CustomerBusinessObject. Run it in the REST Lab.

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. Disable short menus to view the Details tab, which contains custom SQL.

JavaScript resource types

You can also materialize resource responses with JavaScript Resource Type. Explore Demo API, Resource CustomerJSOrdersRest. Select the sub resource (OrdersRest), and view the JavaScript in the the Details pane. Explore JavaScriptMongo (root resource via JavaScript that makes direct calls to Mongo APIs).

MongoDB resource types

You can create resources that map to MongoDB resources:- see
  • CustomerJoinMongoPurchaseOrders (sub resource via JavaScript).  
  • zipcodes (per note above, not available in Jetty package).
Note: The Jetty package does not presume web connectivity, so these are not available in that package.

Custom Endpoints

You can create ad hoc end points 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

Examples above illustrated integration:
  • CustomerJSOrdersRest illustrates integrating SQL and external RESTful data
  • CustomerJoinMongoPurchaseOrder was discussed above - it integrates SQL and NoSQL data into 1 nested resource.

Systems Integration

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

Data Explorer

Switch back to the Demo API. Data Explorer - Experiment with filtering, sorting, updates, Lookups, etc.  Customize with Author Mode.

Manage

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

Rules - Business Logic

Ensure database integrity with a combination of JavaScript and Reactive Logic.

JavaScript

Click Rules > Event: Audit Purchase Order. This is 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 as described here.
  3. Build code using the Expression Help.
The Send Mail example illustrates calling your own loadable Java/JavaScript libraries (Disable Short Menus > API Properties > Libraries).

Reactive Logic

You can save significant time by using Reactive Logic:
  1. Click Check Credit to see the Reactive Logic for this topic (requirement).
  2. Click Edit This Topic for more background.
You can define topics (Disable Short Menus > API Properties > Topics). Topics can include rich text links (e.g., to a Requirements Management system), etc.

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.  Explore it as described below:
  • Attempt to use the Rest Lab with Auth Token SalesRep, and observe "no such resource" on Get to PurchaseOrders

  • Use Security > Sales Rep > REST End Points to authorize access to PurchaseOrders (steps 1-2-3 in the diagram - click the thumbnail)

  • Return to the Rest Lab, and verify you can Get PurchaseOrders
    • Note the number of lines of output

  • Now 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, as it does here.  Navigate to Security > Sales Rep > Permissions (click the thumbnail to the right).  Note the use of @{current_employee_row.employee_id},  current_employee_row is defined on the Globals tab.

For a full description, see the Authentication discussion.


 

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 (Disable Short Menus > 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:
    • an existing database, in the cloud or on-premise, or
    • a new database you create using your existing tools and procedures, or the new database API Creator creates automatically

Advanced Example

You can extend Northwind (created during the introductory Tour) to illustrate Business To Business integration. This illustrates several useful product concepts that can be helpful in real-world projects.

Subpages (1): Logon