Skip to main content

​
Overview

This tutorial walks through the steps of generating a simple API server from scratch using the Sutro API.

​
Before you begin

​
Roles & credentials

​
Tools

  • jq and curl

​
Variables and files

  • You’ll need access to the sutro.key and sutro.crt files created in Step 2 of the Builder authentication setup.
  • Use Step 4 to generate JWTs for your requests and store them in the BUILDER_JWT environment variable.
  • Download the Sutro Certificate Authority (CA) certificate from /certs/ca.crt to secure API requests.

​
Steps

This flow takes you from prompt to deployment so every asset—project, app, and OpenAPI spec—stays under your control the whole time.
1

Create a Project

Start by creating a Project to hold the prompt, application, and generated assets.Add a short description so you remember the goal. In this example, use “My To Do Server”.Call POST /projects
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -X POST \
     -o project.json \
     -d '{"description":"My To Do Server"}' \
     https://sapi.local.withsutro.com/projects
Congratulations! You’ve just created a Sutro Project.The project details now live in project.json; refer to that file in upcoming steps.
2

Create an Application

Next, create an Application. Most Projects contain a single Application.Call POST /projects/{projectId}/applications
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -X POST \
     -o application.json \
     -d '{"description":"My To Do Server"}' \
     https://sapi.local.withsutro.com/projects/$(jq -r '.id' < project.json)/applications
Now you have an Application; two more steps and it will be building…
3

Add a Prompt to the Application

Provide the Application with a prompt so the LLM knows what to generate.Since this tutorial builds a to-do server, use the following prompt:

Build me an API server that helps users track To Dos. It should include the ability to set deadlines on To Do items, as well as mark them completed
Call POST /applications/{applicationId}/prompt.
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -X POST \
     -d '{"prompt":"Build me an API server that helps users track To Dos.\n\nIt should include the ability to set deadlines on To Do items, as well as mark them completed"}' \
     https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/prompt
The prompt is now attached; the Application is ready to generate.
4

Generate the Application

Generating an API server takes a little time, so call the Sutro API to start the process. Monitoring happens in the next step.Call POST /applications/{applicationId}/generation.
 curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
      -cacert ca.crt \
      --key sutro.key \
      --cert sutro.crt \
      -X POST \
      https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/generation
This call will return quickly; our API server is being generated.
5

Monitor for generation to complete

Because curl drives this tutorial, poll the API for the Application’s status.The -s flag limits output to just the Application status, so keep an eye out for unexpected text that might signal local network issues.Call GET /applications/{applicationId}/status.
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -s \
     -X GET \
     https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/status | jq
Make this call every ~10 seconds until the status shows completion.
6

Deploy the Application

The application is ready to deploy.Just like generation, deployment takes time, so this API call starts a deployment and creates a new version.Call POST /applications/{applicationId}/deployment
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -o deployment.json \
     -X POST \
     https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/deployment
The deployment.json file will contain the deploymentId of the deployment (so that we can its status) and the version that was generated.
7

Monitor for the deployment to complete

Monitor deployment the same way as generation.Call GET /applications/{applicationId}/versions/{version}/deployment/{deploymentId}/
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -s \
     -X GET \
     https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/version/$(jq -r '.version' < deployment.json)/deployment/$(jq -r '.deploymentId' < deployment.json) | jq
Once the response says "Successful", the API is ready to use.
8

Start using the API

There are many ways to exercise the new API. Start by getting a description so you know the available paths and methods.Call GET /applications/{applicationId}/versions/{version}/openapi.
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -o openapi.yml \
     -X GET \
     https://sapi.local.withsutro.com/applications/$(jq -r '.id' < application.json)/version/$(jq -r '.version' < deployment.json)/openapi
With the OpenAPI document in hand, pick your favorite API client and start exploring.This API doesn’t have any user credentials because security wasn’t configured. That’s fine for exploration, but add proper authentication before going live with real users’ data.
Your backend is generated, deployed, and documented. Grab the OpenAPI file and start wiring clients with confidence.

​
Reference