Skip to content

Latest commit

 

History

History
566 lines (482 loc) · 16.6 KB

REST-README.md

File metadata and controls

566 lines (482 loc) · 16.6 KB
  __  __ _                _____            __ _ _      
 |  \/  (_)              |  __ \          / _(_) |     
 | \  / |_  ___ _ __ ___ | |__) | __ ___ | |_ _| | ___ 
 | |\/| | |/ __| '__/ _ \|  ___/ '__/ _ \|  _| | |/ _ \
 | |  | | | (__| | | (_) | |   | | | (_) | | | | |  __/
 |_|__|_|_|\___|_|  \___/|_|   |_|  \___/|_| |_|_|\___|
  / ____| |           | |                              
 | (___ | |_ __ _ _ __| |_ ___ _ __                    
  \___ \| __/ _` | '__| __/ _ \ '__|                   
  ____) | || (_| | |  | ||  __/ |                      
 |_____/ \__\__,_|_|   \__\___|_|

Project generator REST API

This document summarizes examples of MicroProfile Starter web application REST API microprofile/starter/1

Each MicroProfile version (mpVersion) offers a suite of specifications (specs) and is implemented by a set of application servers (supportedServers).

In order to get a project zip generated one has to select at least the desired server (supportedServer). The latest mpVersion with no specs but the basic hello world JAX-RS endpoint is used by default then.

Versions

There are currently 6 versions of the API to retain backward compatibility. /api/ is the latest; use e.g. /api/1/ to get the legacy behaviour.

Get available MicroProfile versions

$ curl https://start.microprofile.io/api/mpVersion

["MP22","MP21","MP20","MP14","MP13","MP12"]

Get available supportedServers and specs

Note the order of supportedServers values is pseudorandom each call. Note the JSON formatting was altered for this document.

$ curl https://start.microprofile.io/api/mpVersion/MP22
{
    "supportedServers": [
        "PAYARA_MICRO",
        "LIBERTY",
        "KUMULUZEE",
        "THORNTAIL_V2",
        "HELIDON"
    ],
    "specs": [
        "CONFIG",
        "FAULT_TOLERANCE",
        "JWT_AUTH",
        "METRICS",
        "HEALTH_CHECKS",
        "OPEN_API",
        "OPEN_TRACING",
        "REST_CLIENT"
    ]
}

Getting project

Curl: -O -J makes curl to save the zip file in the current directory. -L makes curl to follow redirects.

Minimal example

Note that latest available MP version for the supportedServer and No available Specs were selected by default.

$ curl -O -J 'https://start.microprofile.io/api/project?supportedServer=THORNTAIL_V2'

curl: Saved to filename 'demo.zip'

On the contrary, when API version 1 or 2 is used, All available Specs are selected by default.

$ curl -O -J 'https://start.microprofile.io/api/2/project?supportedServer=THORNTAIL_V2'

curl: Saved to filename 'demo.zip'

To get All available specs with the current latest API, use selectAllSpecs=true query param in the URL, e.g.:

$ curl -O -J 'https://start.microprofile.io/api/project?supportedServer=THORNTAIL_V2&selectAllSpecs=true'

curl: Saved to filename 'demo.zip'

Examples

The only mandatory attribute is supportedServer. One can omit -v curl flag. Note the optional usage of Etag and If-None-Match.

$ curl -v -O -J -L 'https://start.microprofile.io/api/project?supportedServer=PAYARA_MICRO&artifactId=XXXXX&mpVersion=MP12&selectedSpecs=FAULT_TOLERANCE&selectedSpecs=JWT_AUTH'

< ETag: "dd085c81"

curl: Saved to filename 'XXXXX.zip'

Note we can use ETag dd085c81 from the previous response:

curl -v -O -J -L -H 'If-None-Match: "dd085c81"' 'https://start.microprofile.io/api/project?supportedServer=PAYARA_MICRO&artifactId=XXXXX&mpVersion=MP12&selectedSpecs=FAULT_TOLERANCE&selectedSpecs=JWT_AUTH'

< HTTP/1.1 304 Not Modified

Example with all attributes

$ curl -O -J -L 'https://start.microprofile.io/api/project?supportedServer=LIBERTY&groupId=com.example&artifactId=myapp&mpVersion=MP22&javaSEVersion=SE8&buildTool=MAVEN&selectedSpecs=CONFIG&selectedSpecs=FAULT_TOLERANCE&selectedSpecs=JWT_AUTH&selectedSpecs=METRICS&selectedSpecs=HEALTH_CHECKS&selectedSpecs=OPEN_API&selectedSpecs=OPEN_TRACING&selectedSpecs=REST_CLIENT'

curl: Saved to filename 'myapp.zip'

Use JSON for get the project

By POSTing a JSON string one can get the same result as with using query parameters above.

$ curl -O -J -L -H "Content-Type: application/json" -d '{"mpVersion":"MP14","supportedServer":"TOMEE","selectedSpecs":["REST_CLIENT","CONFIG"]}' 'https://start.microprofile.io/api/project'

curl: Saved to filename 'demo.zip'

Note that if you omit "selectedSpecs":["REST_CLIENT","CONFIG"], nothing but a single Hello World JAX-RS resource is generated. On the other hand, if you add "selectAllSpecs":"true", all available specs within given mpVersion are generated. The legacy /api/2/ and prior behaviour was to give you all available specs when none was selected.

This is how one can have the JSON stored in a file:

$ curl -O -J -L -H "Content-Type: application/json" -d @my.json 'https://start.microprofile.io/api/project'

curl: Saved to filename 'demo.zip'

JSON All attributes used

$ cat all.json
{
  "groupId": "com.example",
  "artifactId": "myapp",
  "mpVersion": "MP22",
  "javaSEVersion": "SE8",
  "supportedServer": "THORNTAIL_V2",
  "buildTool": "MAVEN",
  "selectedSpecs": [
    "CONFIG",
    "FAULT_TOLERANCE",
    "JWT_AUTH",
    "METRICS",
    "HEALTH_CHECKS",
    "OPEN_API",
    "OPEN_TRACING",
    "REST_CLIENT"
  ]
}

$ curl -O -J -L -H "Content-Type: application/json" -d @all.json 'https://start.microprofile.io/api/project'

curl: Saved to filename 'myapp.zip'

JSON Minimal example

Add "selectAllSpecs":"true" to get all specs examples.

$ curl -O -J -L -H "Content-Type: application/json" -d '{"supportedServer":"KUMULUZEE"}' 'https://start.microprofile.io/api/project'

curl: Saved to filename 'demo.zip'

Errors

Note that if you select an invalid combination of selectedSpecs and supportedServer and mpVersion you get an error, e.g.:

$ curl -v -O -J -L 'https://start.microprofile.io/api/project?supportedServer=HELIDON&selectedSpecs=REST_CLIENT'

curl: Saved to filename 'error.json'

$ cat error.json 
{"error":"One or more selectedSpecs is not available for given mpVersion","code":"ERROR003"}

What happened: We did not specify mpVersion, so the latest for the given server at the time was selected by default, it means MP12 at the time of writing of this example. MP12 does not offer spec REST_CLIENT as we can see:

$ curl https://start.microprofile.io/api/mpVersion/MP12
{
  "supportedServers": [
    "PAYARA_MICRO",
    "THORNTAIL_V2",
    "KUMULUZEE",
    "TOMEE",
    "HELIDON",
    "WILDFLY_SWARM",
    "LIBERTY"
  ],
  "specs": [
    "CONFIG",
    "FAULT_TOLERANCE",
    "JWT_AUTH",
    "METRICS",
    "HEALTH_CHECKS"
  ]
}

Windows users

curl.exe examples

Curl is widely available on Windows too, e.g. https://curl.haxx.se/windows/

C:\curl\bin>curl -O -J https://start.microprofile.io/api/project?supportedServer=THORNTAIL_V2&selectAllSpecs=true

curl: Saved to filename 'demo.zip'

C:\curl\bin>curl -O -J "https://start.microprofile.io/api/project?supportedServer=TOMEE&selectedSpecs=JWT_AUTH&selectedSpecs=CONFIG"

curl: Saved to filename 'demo.zip'

Powershell examples

Minimal

PS C:\> Invoke-WebRequest -OutFile project.zip -Uri https://start.microprofile.io/api/project?supportedServer=LIBERTY

Using JSON

PS C:\> type .\all.json
{
  "groupId": "com.example",
  "artifactId": "myapp",
  "mpVersion": "MP22",
  "javaSEVersion": "SE8",
  "supportedServer": "THORNTAIL_V2",
  "selectedSpecs": [
    "CONFIG",
    "FAULT_TOLERANCE",
    "JWT_AUTH",
    "METRICS",
    "HEALTH_CHECKS",
    "OPEN_API",
    "OPEN_TRACING",
    "REST_CLIENT"
  ]
}
PS C:\> $headers = @{
>>   "Content-Type" = "application/json"
>> }
PS C:\> Invoke-WebRequest -InFile ./all.json -OutFile project.zip -Method Post -Uri "https://start.microprofile.io/api/project" -Headers $headers

Integration with IDEs

If it is preferred to acquire all valid options in a one request the supportMatrix call is recommended. The integration code SHOULD use Etag response header and If-None-Match request header so as to avoid unnecessary deserialization of identical responses.

The supportMatrix/servers endpoint returns the support for a Build Tool (Maven and or Gradle) for each MP version and runtime combination.

MicroProfile versions as keys

$ curl -i https://start.microprofile.io/api/supportMatrix
...
ETag: "44730639"
...
{
    "configs": {
        "MP30": {
            "supportedServers": [
                "LIBERTY",
                "THORNTAIL_V2",
                "HELIDON"
            ],
            "specs": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ]
        },
        "MP22": {
            "supportedServers": [
                "THORNTAIL_V2",
                "LIBERTY",
                "KUMULUZEE",
                "PAYARA_MICRO",
                "HELIDON"
            ],
            "specs": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ]
        },
...
...other MP versions removed for brevity...
...
    },
    "descriptions": {
        "CONFIG": "Configuration - externalize and manage your configuration parameters outside your microservices",
        "OPEN_API": "Open API - Generate OpenAPI-compliant API documentation for your microservices",
        "HEALTH_CHECKS": "Health - Verify the health of your microservices with custom verifications",
        "REST_CLIENT": "Rest Client - Invoke RESTful services in a type-safe manner",
        "FAULT_TOLERANCE": "Fault Tolerance - all about bulkheads, timeouts, circuit breakers, retries, etc. for your microservices",
        "JWT_AUTH": "JWT Propagation - propagate security across your microservices",
        "OPEN_TRACING": "Open Tracing - trace the flow of requests as they traverse your microservices",
        "METRICS": "Metrics - Gather and create operational and business measurements for your microservices"
    }
}

Using value from ETag in If-None-Match:

$ curl '-HIf-None-Match: "44730639"' -i https://start.microprofile.io/api/supportMatrix
...
HTTP/1.1 304 Not Modified

Server implementations as keys

$ curl -i https://start.microprofile.io/api/supportMatrix/servers
...
ETag: "7b99230f"
...
{
    "configs": {
        "LIBERTY": {
            "MP14": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP22": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP30": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP20": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP21": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP13": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP12": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS"
            ]
        },
        "PAYARA_MICRO": {
            "MP14": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP22": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP20": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP21": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP12": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS"
            ],
            "MP13": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ]
        },
        "THORNTAIL_V2": {
            "MP22": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP30": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP21": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ],
            "MP12": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS"
            ],
            "MP13": [
                "CONFIG",
                "FAULT_TOLERANCE",
                "JWT_AUTH",
                "METRICS",
                "HEALTH_CHECKS",
                "OPEN_API",
                "OPEN_TRACING",
                "REST_CLIENT"
            ]
        }
...
...other servers removed for brevity...
...
    },
    "descriptions": {
        "CONFIG": "Configuration - externalize and manage your configuration parameters outside your microservices",
        "OPEN_API": "Open API - Generate OpenAPI-compliant API documentation for your microservices",
        "HEALTH_CHECKS": "Health - Verify the health of your microservices with custom verifications",
        "REST_CLIENT": "Rest Client - Invoke RESTful services in a type-safe manner",
        "FAULT_TOLERANCE": "Fault Tolerance - all about bulkheads, timeouts, circuit breakers, retries, etc. for your microservices",
        "JWT_AUTH": "JWT Propagation - propagate security across your microservices",
        "OPEN_TRACING": "Open Tracing - trace the flow of requests as they traverse your microservices",
        "METRICS": "Metrics - Gather and create operational and business measurements for your microservices"
    }
}

Using value from ETag in If-None-Match:

$ curl '-HIf-None-Match: "7b99230f"' -i https://start.microprofile.io/api/supportMatrix/servers
...
HTTP/1.1 304 Not Modified