Rest-API Plugin

The Rest-API plugin facilitates the use of the AaC application through a RESTful API interface. A RESTful API is an architectural style where an application interface sends and receives data through HTTP requests.

rest-api Command

Help Command for rest-api

The section below is an example of the terminal output for the -h flag.

$ aac rest-api -h
Usage: aac rest-api [OPTIONS]

Options:
  --host TEXT     Set the hostname of the service. Useful for operating behind
                  proxies.  [default: 0.0.0.0]
  --port INTEGER  The port to which the RESTful service will be bound.
                  [default: 8080]
  -h, --help      Show this message and exit.

Request Contents

A request to the HTTP server contains a request method. The four request methods used by the interface are:

• GET, which receives and reads data.

• PUT, which updates data that already exists on the server.

• POST, which creates data.

• DELETE, which removes data.

A RESTful API request also needs to contain a unique resource identifier which contains a path to the resource that the method is acting on.

Response Contents

The two parts of a response from a HTTP server are the response status, and the message body.

The four most common response statuses are:

• 200 OK

  • This indicates that a request has succeeded

• 204 No Content

  • This indicates that a request succeeded, but there was no data for the client to receive.

• 400 Bad Request

  • This indicates that the server could not understand the request, and is usually caused by incorrect syntax

• 404 Not Found

  • This indicates that the server could not find a resource with the given unique resource identifier.

Message bodies will contain the data requested by a GET command in either a JSON or XML format.

Request Method Commands

Request Method Argument Types

Some request method commands require parameter arguments. In order for arguments to be accepted by the RESTful API, they have to derive from a type called BaseModel. Included in this plugin are several BaseModel derived types corresponding to objects used by the AaC Application. When passing AaC objects as arguments, they must first be converted to one of the derived types. Listed below are several AaC types and their corresponding BaseModel types, along with an included Python method to convert the two.

AacCommand -> CommandModel

CommandModel = to_command_model(AaCCommand)

AacCommandArgument -> CommandArgumentModel

CommandArgumentModel = to_command_argument_model(AacCommandArgument)

Definition -> DefinitionModel

DefinitionModel = to_definition_model(Definition)
Definition = to_definition_class(DefinitionModel)

AaCFile -> FileModel

FileModel = to_file_model(AaCFile)
AaCFile = to_file_class(FileModel)

Other included BaseModel types that do not correspond to specific AaC types are:

CommandRequestModel - A class which contains a command name and a list of arguments FilePathModel - A class which contains a file uri. FilePathRenameModel - A class for renaming a file, which contains a file uri to replace with the new file uri.

Available Request Method Commands

The requests available to be sent using the REST-API plugin are listed below. These examples use the request method with the unique resource identifier as the first argument, followed by any other required arguments of the method. The section under each command will contain the desired response status.

get("/files/context")

HTTPStatus: 200 OK This command reads and returns a list of files in the current LanguageContext.

get("/files/available")

HTTPStatus: 200 OK This command reads and returns a list of files in the workspace available for import into the active context. The list of files returned does not include files already in the context.

get("/file", file_uri: str)

HTTPStatus: 200 OK This command accepts file uri as an argument and returns the requested file.

post("/files/import", file_models: list[FilePathModel])

HTTPStatus: NO_CONTENT This command imports a list of files into the LanguageContext.

put("/file", rename_request: FilePathRenameModel)

HTTPStatus: NO_CONTENT This command renames a file, or updates its uri.

delete("/file", file_uri: str)

HTTPStatus: NO_CONTENT This command removes the file from the active LanguageContext.

get("/definitions")

HTTPStatus: 200 OK This command returns a list of definitions in the active LanguageContext.

get("/definition", name: str)

HTTPStatus: 200 OK This command accepts a definition name as a string, and returns a list of definitions with that name.

post("/definition", definition_model: DefinitionModel)

HTTPStatus: NO_CONTENT This command Adds a definition to the active LanguageContext.

post("/definitions", definition_models: list[DefinitionModels])

HTTPStatus: NO_CONTENT This command Adds a list of definitions the the active LanguageContext.

put("/definition", definition_model: DefinitionModel)

HTTPStatus: NO_CONTENT This command updates a definition in the active LanguageContext.

delete("/definition", name: str)

HTTPStatus: NO_CONTENT This command removes a definition from the active LanguageContext.

get("/context/schema", key: str)

HTTPStatus: OK This command takes in a root key and returns the corresponding root YAML schema.

get("/context/root_keys")

HTTPStatus: OK This command returns a list of root keys from the active LanguageContext.

get("/command")

HTTPStatus: OK Returns a list of all available commands.

post("/command", command_request: CommandRequestModel)

HTTPStatus: OK This command executes the given AaC command.

gen-openapi-spec Command

Help Command for gen-openapi-spec

$ aac gen-openapi-spec -h
Usage: aac gen-openapi-spec [OPTIONS] OUTPUT_DIRECTORY

Options:
  -h, --help  Show this message and exit.

gen-openapi-spec Usage and Return

The gen-openapi-spec command returns a JSON file containing the open API schema. Below is an example of a successful run of the command.

$ aac gen-openapi-spec ./output_directory
Successfully wrote the OpenAPI spec to ./output_directory/AaC_OpenAPI_Schema.json.

Executing the above command will create a file in ./output_directory called AaC_OpenAPI_Schema.json, which will contain the API schema in a JSON format.