đQuickstart
You'll need a Formata Space for your team in our web application. These docs assume you've contacted us to create a subscription and get set up.
To better understand what Formata is, check out our What and Why page.
The best way to get started with Formata is by example! In this quickstart guide, we'll create an example API together. The API is also available on the marketplace in-app - you're welcome to follow along and create your own, or clone this example API into your space by navigating into your Space and then into the marketplace.
Hub Layout, Navigation, and Terminology
Hub - the Formata Web App.
Space - where your team creates, manages, and observes APIs within the Hub.
Member - a team member who has access to your Space as a collaborator.
Endpoint - an API endpoint within the Hub that has a unique subject (not an HTTP endpoint).
Subject - the path used to call/execute an Endpoint. Ex. "formata.v1.quickstart.hello-world".
Ase - Formata's data runtime.
AseScript - Formata's drop-in replacement to JSON for passing data to Endpoints and Services.
Service - an application running within Formata's Lattice, tasked with executing Endpoint Jobs.
Lattice - a global network of connected services that Formata provides and manages.
Job - an (async by default) task that the core Formata Service interprets to perform Endpoint actions. These are specified within a Pipeline per Endpoint.
Pipeline - a sequential array of Jobs defined per Endpoint for Services to execute.
Handler - defines the pipeline and script for each Endpoint.
Message - an Endpoint request body (usually AseScript, but can be JSON, YAML, XML, etc...).
Reply - a response from an Endpoint.
The Hub is organized like a file explorer, allowing users to browse their APIs and endpoints in a very organized and intuitive fashion. Each space has a display name and a path name, used to reference the Space from both in-app and in each API call. The current path is shown at the top of the app, where one can navigate or search for anything available to them in the app.
On the home page of the Hub, one can see their active subscriptions and current period usage on the "Account" page. The "Profile" page allows one to opt into or out of our email list. Last, but not least, on the "Spaces" page, one can navigate into the Spaces they're a Member of (if it has a subscription). If stuck at this step, don't hesitate to contact us.
Create an API
Now that you should have a general feel for how the Hub is organized, navigate into your Space and create a new API named "Formata Quickstart", with the path "quickstart" by clicking on the + icon. Now navigate into the API - you should see a screen similar to:
Create an Endpoint
Click on "Create a new endpoint" or on the + icon to create a new Endpoint in your new API.
Display Name - can be whatever you'd like - used to distinguish between endpoints in the API and to recognize the endpoint while searching for it.
Description - used to further explain what the endpoint does so others understand its purpose.
Endpoint Path Name - file explorer-like path name, used to organize endpoints within the Hub only.
Version - the version of this endpoint - used when executing it from your applications.
Route - how the endpoint is referenced when executing it from your applications.
After clicking on "Create Endpoint", you should now see the endpoint under the API. Each endpoint in this list has labels associated with it to help you understand at a glance which ones are in use/published, if the endpoint is public or private, what the version is, and the name to use when calling it from your applications.
Now we can create our Endpoint pipeline! đ First, though, a quick overview of this page.
In the middle of the page, the entire endpoint subject is shown - this is all that is needed to call this endpoint from your applications. The subject pattern is <space path name>.<version>.<api path name>.<endpoint route name>.
Under the endpoint subject is the endpoint Handler AseScript editor. For now, just think of AseScript as JSON, it's a drop-in replacement after all. We'll go into more detail on this in the AseScript section of these docs.
To publish, update, and unpublish the endpoint, use the buttons that appear right next to the endpoint name and description.
On the right side, you'll see two more editors used for testing/playing with this Endpoint. The Hub uses the same client SDK here to call your Endpoint on your behalf just like your application would. If it's a private API, you'll see a key dropdown, enabling you to specify which API token to use when testing your Endpoint. More on private APIs later. The top editor is also AseScript, allowing you to send a Message (request body) to this Endpoint. In Formata, we aren't using HTTP, so requests are really messages with subjects (hence the alternative terminology). Lastly, the editor in the lower right shows a read-only JSON Reply (response) from a test call to this Endpoint. We show it in JSON, but within your application, you can choose what format you'd like (JSON, YAML, TOML, XML, etc...). Remember, Ase is format agnostic.
Hello, World!
Let's create our "Hello, World!" AseScript Handler! For now, just think of AseScript as JSON - we'll dig into the differences later. Copy and paste the following handler into the editor:
Every Handler has a Pipeline array of Jobs, telling the Service what to do when this Endpoint is called. Each Job is required to have a name - this is how the Reply is organized since every Job is asynchronous by default. For this Job, we are specifying some static data that should be included within the Reply, under the object "Hello".
Click "Publish" to make this Endpoint available, then on the right side, click "Test Endpoint".
In the lower right Reply editor, you'll see the output from testing this Endpoint. Formata constructs an object named "Reply" that gets sent back per call. Each Job in the pipeline gets to add its own reply to the Reply object, under the name of the Job.
In this case, the pipeline has one Job, named "Hello", with a static "message" field. If the Handler instead has multiple Jobs, we'll get multiple Reply objects.
Messages
When calling an Endpoint, a Message is how we pass dynamic data back and forth. This is not an HTTP endpoint, so we use an alternative terminology. The client SDK uses a Web Socket to communicate with the Lattice (if you're wondering).
REST Job
Obviously, Jobs don't just return static data - they can do all sorts of things. One of those things is a REST request. We'll go into more detail on Jobs and REST requests later on, but here is a quick example of two async REST requests to a country information API.
Handler (notice it's not JSON anymore... important later on):
Now, try combining the REST job with static data to see what you get!
Pipeline Control Flow
Jobs are async by default but can be awaited - ensuring a job completes before moving to the next. In this case, the USA Job will be completed before the UK job is allowed to start.
Next Steps
Congrats on creating your first Endpoint in Formata! đ
In the next pages, we'll delve deeper into AseScript and how Formata interprets your Endpoint Handlers. We'll implement entire APIs, manipulate data, and get into how Formata can improve the performance of your integrations.
Last updated
