Skip to main content

Your first Godspeed Project

Follow these steps to set up and launch your new Godspeed project:

  1. Create a new project:

      godspeed create my-project

  2. Navigate to the project directory:

      cd my-project

  3. Start the development server:

      godspeed serve

Accessing and Testing Your API with Swagger UI​

Godspeed automatically generates interactive API documentation using Swagger UI.

  1. Access Swagger UI: The Swagger UI is typically available at:

        http://<BASE_URL>:<PORT>/<http_docs_endpoint>`

    By default, this is:

    http://localhost:3000/api-docs

    If you need to customize the default port (3000) or the Swagger endpoint (/api-docs), you can modify the ./src/eventsources/http.yaml file.

  2. Test the /helloworld API:

    • In the Swagger UI, locate the /helloworld endpoint.
    • Click the Try it out button.
    • You will be prompted to fill in a name parameter. Enter a name (e.g., "John") and send the request.
    • The server will return the following response: 
      Hello `John`

Understanding Your First Godspeed Project​

Let's dive into the structure and core concepts of your newly created Godspeed project.

Project Scaffolding​

Godspeed generates a well-organized project structure:

  • The framework creates various folders inside, including:
tip

For a deeper understanding of the project's scaffolding structure, refer to the Walkthrough section

Why the /helloworld API Requires a Name​

The /helloworld API endpoint asks for a name parameter because it's configured to require it as part of the query string.

Let's examine the event schema for this API in src/events/helloworld.yaml:

http.get./helloworld: # `http` server listening via `get` method on `/helloworld` endpoint
  fn: helloworld # the function handler to be called for this endpoint, available in `src/functions`
  params: # JSON-Schema of API parameters like query, headers, path params. Note: This is set as per Swagger standard's `parameters` syntax
    - name: name  # This is our name query param
      in: query    # Notice the in: query, it can be `path` or `headers` as well
      required: true # true means `name` parameter is required
      schema:
        type: string
  responses: # JSON-Schema of API responses for different status codes. Note: This is set as per Swagger standard's `responses` syntax
    200:
      content:
        application/json:
          schema:
            type: string

In this helloworld.yaml file:

  • params: This section describes the input the API expects. Here, it expects a name parameter.
  • name: name: Specifies that the query parameter is named name.
  • in: query: Indicates that the name parameter should be included in the URL's query string (e.g., /helloworld?name=John). It can also be path or headers.
  • required: true: The name parameter is mandatory for the API to function.
  • schema: { type: string }: The name parameter must be a string, enforcing text input.
tip

In the Godspeed meta-framework, every API (REST or GraphQL) and message (websocket, cron, message bus) is referred to as an event. All events trigger workflows/functions, which act as event handlers (see the fn: instruction in the YAML above). Synchronous events return a response, while asynchronous events do not.

This naming convention might be new to you. While the broader developer community typically refers to only async events (like Kafka or websocket messages) as events, Godspeed considers both synchronous APIs (REST, GraphQL) and asynchronous events (Message bus, websocket, cron) as events.

Testing API Input and Output Validation​

Godspeed provides built-in validation for data sent to and from your APIs, ensuring data integrity.

  1. Test missing name parameter: Open your browser and navigate to localhost:3000/helloworld. Alternatively, run curl -i localhost:3000/helloworld from your terminal. This will return a 400 error, as you haven't provided the required name query parameter:

    {
      "validation_error": {
        "success": false,
        "code": 400,
        "message": "request validation failed.",
        "error": "must have required property 'name' in query",
        "data": {
          "message": "The API cannot be executed due to a failure in request params schema validation.",
          "error": {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
              "missingProperty": "name"
            },
            "message": "must have required property 'name' in query"
          }
        }
      }
    }

  2. Test with name parameter: Now, navigate to localhost:3000/helloworld?name=mastersilv3r. This should work correctly:

    Hello mastersilv3r

API Collections​

Godspeed helps you easily work with API clients.

  • Swagger Collection: Access the automatically generated Swagger collection for your project from the /docs folder within your project.

  • Postman Collection: To get a Postman Collection, simply import the Swagger file from src/docs into Postman.

Video Tutorial - Short​

There is a longer and detailed introduction video as well, below on this page.

If you want some pre-made examples please check the examples repository

Video Tutorial - Longer and in depth​

Walkthrough the Loan Origination System project made using our meta framework