This chapter deals with the registration process and how to offer your APIs.

1. API Definition
2. Register API
3. Change resource names
4. Resource whitelist/blacklist
5. List all your APIs
6. Show API
7. Update API
8. Delete API
9. API Evaluation
10. Gateway Open API Specification

To register an API the system requires an OpenAPI specification v3 of your API.

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API.

For more information about OpenAPI visit the homepage or look into the decisions of the implementation chapter.

The registration of you API is simple. Just send your OpenAPI definition to the system. You can pass the OpenAPI definition via url, text or file.

# system url
url="http://localhost/gateway/api?api_token=<api-token>"

# option a) OpenAPI definition via url
data='{
    "url": "<url-to-openapi-yaml>"
}'
# option b) OpenAPI definition via text
data='{
    "definition": "<openapi-yaml-as-string>"
}'
# option c) OpenAPI definition via file
data='{
    "file": "<file-upload-with-openapi-yaml>"
}'

# send request
curl -d "$data" -H "Content-Type: application/json" -X POST "$url"

Note: The response is the saved API with its Id.

Note: RESTful resources should always be plural and in english. Due to some reasons some APIs ignore this unwritten rule. To match the resource user and users together and fix the singular form, each resource name will be tried to pluralize.

If you are using non standard resource names you have to change them when you register the API. Otherwise a resource matching will not be possible.

url="http://localhost/gateway/api?api_token=<api-token>"
data='{
    "url": "<url-to-openapi-yaml>",
    "dictionary": {
		"Benutzer": "users",
		"Kommentare": "comments"
	}
}'
curl -d "$data" -H "Content-Type: application/json" -X POST "$url"

Note: If possible, a resource will be automatically pluralized.
/user -> /users

To restrict your offered resources you can use a whitelist or blacklist. With the keywords include and exclude you are able to define which resources we want to offer and which not.

# whitelist with include
url="http://localhost/gateway/api?api_token=<api-token>"
data='{
    "url": "<url-to-openapi-yaml>",
    "include": [
        "/users",
        "/users/{id}/comments",
        "..."
    ]
}'
curl -d "$data" -H "Content-Type: application/json" -X POST "$url"

# blacklist with exclude
url="http://localhost/gateway/api?api_token=<api-token>"
data='{
    "url": "<url-to-openapi-yaml>",
    "exclude": [
        "/users",
        "/users/{id}/comments",
        "..."
    ]
}'
curl -d "$data" -H "Content-Type: application/json" -X POST "$url"

To get a list of all your offers you can log yourself in on the webpage or request them as a JSON response.

curl "http://localhost/gateway/api?api_token=<api-token>"

To get the data of one of your offers you can log yourself in on the webpage or request them as a JSON response.

curl "http://localhost/gateway/api/<api-id>?api_token=<api-token>"

An API update is nothing else then a deletion of the existing API and a store of the new one.
Like in the registration it is possible to pass the OpenAPI definition via url, text or file.

url="http://localhost/gateway/api/<api-id>?api_token=<api-token>"
data='{
    "url": "<url-to-openapi-yaml>"
}'
curl -d "$data" -H "Content-Type: application/json" -X PUT "$url"

Instead of PUT you can also you PATCH.

To delete an API offer just send a delete request.

curl -X DELETE "http://localhost/gateway/api/<api-id>?api_token=<api-token>"

Each resource is evaluated by its response or transfer time.
You can create a cron job to evaluate all resources periodically or start it manually.
With each resource changes, e.g. new API registration, the system will start an evaluation automatically.

# manually start api generation
php artisan api:evaluate
# or
./devops art api:evaluate

The RESTful API Gateway will always generate a new OpenAPI specification or definition after API changes and api evaluations. This specification is available under /openapi.yaml.

# manually start api generation
php artisan api:generate-definition
# or
./devops art api:generate-definition