Getting Started

So You Want An API?

Please make sure JDK 17, Maven, and Docker Engine have been installed 🤗

• We offer instruction on how to install JDK 17 and Maven
• We also offer links to Docker Engine installation

Instantiating the Template

Please visit Astraios GitHub and either

1. clone the repo with git clone git@github.com:paion-data/astraios.git, or
2. make it a template instantiation with our own webservice name by doing the following:

Creating Models

Astraios models are some of the most important code in any webservice project. Our models are the view of our data that we wish to expose. In this example we will be modeling a book since most people have a high-level familiarity with books in life. Our Book model has been packaged as a JAR file in a separate Maven project. It has already been published to Maven Central and will be installed in this tutorial by default so that user don't need to do anything to set up the data model at this moment

Running

With data models defined, can run my-webservice

cd my-webservice
mvn clean package --settings settings.xml.example
MODEL_PACKAGE_NAME=com.paiondata.astraios.data.models docker compose up --build --force-recreate

Note that the settings.xml is the Maven config file for loading the data model

info

• com.paiondata.astraios.data.models is the name of the model in the aforementioned data model project
• The data model is loaded via a special-purpose Maven settings file called settings.xml.example, which instructs my-webservice to load data models. It's essentially the regular ~/.m2/settings.xml:

If everything runs successfully, we should be able to see the following output at end of the command line output:

web-1  | 25-06-2024 04:41:53.654 [main] [Elide, ] INFO  o.a.coyote.http11.Http11NioProtocol.log - Starting ProtocolHandler ["http-nio-8080"]
web-1  | 25-06-2024 04:41:53.676 [main] [Elide, ] INFO  o.s.b.w.e.tomcat.TomcatWebServer.start - Tomcat started on port(s): 8080 (http) with context path ''
web-1  | 25-06-2024 04:41:53.709 [main] [Elide, ] INFO  com.paiondata.astraios.App.logStarted - Started App in 14.755 seconds (process running for 16.004)

A MySQL database container has also started alongside and is accessible via

mysql -h localhost -D elide -P 3306 --protocol=tcp -u root -proot

All data is persisted in a database called elide

Writing Data

Installing GraphiQL

GraphiQL offers a user-friendly UI for issuing GraphQL queries and displaying query responses. We can use it for the API call below.

• Mac uses Homebrew

  brew install --cask graphiql

• Windows binary can be downloaded from the release page. Then install the downloaded .exe file

• Linux users can follow the official documentation

When installed, the GraphiQL user interface looks like the following:

Inserting Data

We have defined our views on the database and exposed those views over HTTP. Next let's use cURL to put data in the database.

JSON-API

curl -X POST http://localhost:8080/v1/data/book \
    -H "Content-Type: application/vnd.api+json" \
    -H "Accept: application/vnd.api+json" \
    -d '{"data": {"type": "book", "attributes": { "title": "Pride and Prejudice" }}}'

GraphQL

curl -X POST "http://localhost:8080/v1/data" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"  \
    -d '{ "query" : "mutation { book(op: UPSERT, data:{title: \"Pride & Prejudice\"}) { edges { node { id title } } } }" }'

(GraphQL) Query

mutation {
  book(op: UPSERT, data:{title: "Pride & Prejudice"}) {
    edges {
      node {
        id
        title
      }
    }
  }
}

When we run that cURL call we should see a bunch of JSON returned, that is our newly inserted object!

JSON-API

{
   "data":{
      "type":"book",
      "id":"1",
      "attributes":{
         "title":"Pride and Prejudice"
      }
   }
}

GraphQL

{
   "data":{
      "book":{
         "edges":[
            {
               "node":{
                  "id":"4",
                  "title":"Pride & Prejudice"
               }
            }
         ]
      }
   }
}

Looking at Our Data

Web Browser

Simply open up our favorite browser and hit http://localhost:8080/v1/data/book

tip

It is recommended to view result with some JSON formatter browser extension for better viewing experience

JSON-API

curl "http://localhost:8080/v1/data/book"

GraphQL

curl -X POST "http://localhost:8080/v1/data" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"  \
    -d '{ "query" : "{ book { edges { node { id title } } } }" }'

(GraphQL) Query

{
  book {
    edges {
      node {
        id
        title
      }
    }
  }
}

Modifying Data

Notice that, when we created it, we did not set any of the attributes of our new book record. Updating our data to help our users is just as easy as it is to add new data. Let's update our model with the following cURL call.

JSON-API

curl -X PATCH http://localhost:8080/v1/data/book/1 \
    -H "Content-Type: application/vnd.api+json" \
    -H "Accept: application/vnd.api+json" \
    -d '{"data": {"type": "book", "id": "1", "attributes": { "title": "Emma" }}}'

GraphQL

curl -X POST "http://localhost:8080/v1/data" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"  \
    -d '{ "query" : "mutation { book(op: UPSERT, data: {id: \"1\", title: \"Emma\"}) { edges { node { id title } } } }" }'

(GraphQL) Query

mutation {
  book(op: UPSERT, data: {id: "1", title: "Emma"}) {
    edges {
      node {
        id
        title
      }
    }
  }
}