This guide describes how to convert your API Runtime Services application using the MVC framework to work in the API Builder framework.
For details about API Builder, see API Builder Tools.
Create an API Builder project
Before starting, first create an API Builder project by executing the command below in your workspace directory:
If you have any special settings or dependencies in your API Runtime Services project's
package.json file, add them to the same file in your new API Builder project. Do not overwrite any existing keys.
Express app instance
To access the Express instance in an API Builder project, use the
app property of the API Builder instance. For the API and Route components, an API Builder instance is passed to the
response objects as the
An API Builder application does not include socket.io by default. To include socket.io in an API Builder application:
- In the
socket.ioas a dependency.
- In the
app.js, in the
startedevent listener, load the socket.io module and pass it the server instance ( API Builder instance's
serverproperty), then make API calls to the socket.io instance. If you assign the socket.io instance to a property of the API Builder instance, you can access the socket.io instance with that property wherever an API Builder instance is passed to a method.
- Any client-side code, such as the view templates, will need to include the
socket.io.jsclient script. Note that when the client connects to the socket.io server ( API Builder application), you will need to update the URL when switching between testing the project locally or when it's published to API Runtime Services.
The following example creates a basic chat application.
Add socket.io as a dependency to the API Builder project.
Loads the socket.io module and creates an instance.
Then, add the socket.io client code to your views or other client-side code.
Note you need to implement an API Builder Route to render the HTML.
If you add any logic to the
stop() methods in the
app.js file, you can add the same logic in the API Builder instance's event listeners for the
stopping events, respectively.
The API Runtime Services project logs in and out of an ArrowDB account when the application starts and stops. The same method calls can be added to the event listeners in an API Builder application.
All routes declared in the
config.json file of your API Runtime Services application may be declared as a:
- API Builder Route located in the
web/routesfolder of the API Builder project if the route renders UI. For details, see the example below and API Builder Web.
- API Builder Model if the route is a simple data object stored in the cloud that you want to have standardized HTTP endpoints. For details, see Models.
- API Builder API if the route performs more complex operations and you want to have a custom HTTP endpoint. For details, see APIs - Legacy.
config.json file defines a route that when someone accesses
SERVER_ADDRESS/foobar, the API Runtime Services application executes the
bar() method in the
To use the same route in API Builder, create a CommonJS module, which loads the
arrow module, then call the module's
Router.extend() method to declare the route. Pass a dictionary to the
extend() method with the following keys defined (all keys are required):
|name||The name of your route.|
|path||The endpoint/path for your route.|
|method||HTTP verb ('DELETE', 'GET', 'POST' or 'PUT').|
|description||A description for your route. This is used for documentation purposes.|
|action||Function that allows you to interact with API Builder APIs and Models and send data to your template engine.|
Finally, expose the route using the
All filters declared in the
config.json file of your API Runtime Services application may be declared as an Arrow Block module that can be assigned to the
before property in the definition file of an API Builder Model or API.
For all websockets declared in the
config.json file of your API Runtime Services application, you will need to add an event listener to the socket once a connection is established, which requires socket.io to be added to the project. For details, see the socket.io instance section above.
config.json file defines a websocket that whenever a
newChatMsg is received, the API Runtime Services application executes the
receiveMessage() method in the
All logic declared in the API Runtime Services controllers should be moved to the API Builder Route module in the
web/routes folder of the API Builder project or API Builder API module. For details, see the above.
All logic declared in the API Runtime Services filters should be moved to the API Builder Block module.
All logic declared in API Runtime Services websockets will need to be declared with the socket event listener, which requires socket.io to be added to the project. For details, see the above.
Copy all files in the
public folder of your API Runtime Services application to the
web/public folder in the new API Builder project.
Copy all files in the
views folder of your API Runtime Services application to the
web/views folder in the new API Builder project.
Run the API Builder project
After you have made your changes, to test the project, run or publish the API Builder project.
To run the API Builder project locally, execute the following command from the project's directory:
Publish the API Builder project
To publish the API Builder project to the cloud, execute the following command from the project's directory:
This will produce a new URL, different from that of your existing API Runtime Services project. Follow the instructions in the API Runtime Services section of the platform migration page to replace your existing API Runtime Services project and update clients that use it.