Language Syntax

The SpecAPI syntax aims to be simple and concise, we define specifications in *.specapi files.

The first thing we need to put in a *.specapi file is the package declaration.

package org.specapi.syntax.example

The API block

We declare an API using the api keyword, followed by a name to uniquely identify the API, and then the default base url as follows.

package org.specapi.syntax.example

api ExampleAPI http://example-api.specapi.org {
    // TODO: define API methods
}

API Methods

Within an API block, we can define methods, using either the get, put, post, delete keywords which represent our desired HTTP verb for a given method.

Methods can have request and response blocks where we can define which type of entity we expect for a request or response, we will look at entities later, for this section we will assume they are already defined elsewhere.

GET methods

The following example defines a simple get method.

get getThings /things {
    response Thing[]
}

The get method first defines the HTTP verb get, following an identifier for this get method, and then a path /things.

Inside the get method we define a response block, which returns an entity array of Thing. Entities will be discussed later. we use the [] to define that Thing is an array.

POST methods

The next example shows a post method.

post createThing /things {
   request Thing
   response Status
}

In this example, we use the keyword post to specify that this method is a POST, followed by an identifier createThing and then a path /things.

We define a request of type Thing, which says that the API expects type Thing in its post body, the response block of type Status.