Client from the specification¶

For languages without a ready-made package, generate the client yourself from the specification of the verification API. The basis is the openapi.yaml file according to OpenAPI 3.1.0. It describes the POST /verify and POST /verify-credentials endpoints of the https://api.eu-captcha.eu/v1 server.

Note

For PHP, Symfony and Laravel, Python, Django, Ruby, and Java, ready-made packages are available. Generate your own client only for languages that are not listed there. See Integration.

Requirements¶

The following requirements must be met:

Requirement	Value
Specification	The `openapi.yaml` file is available
Tool	`openapi-generator-cli`; Myra generates its own clients with version 7.18.0

Generating a client¶

To generate a client, run the following command:

openapi-generator-cli generate -i openapi.yaml -g <generator> -o <output directory>

Replace <generator> with the name of the generator you want. The following examples show the calls used by Myra:

Destination	Command
Spring	`openapi-generator-cli generate -i openapi.yaml -g spring -o spring`
Node.js with TypeScript	`openapi-generator-cli generate -i openapi.yaml -g typescript-node -o typescript-node`

For other languages — for example Go, C#, or Rust — enter the name of the applicable generator. The list of the generators is part of the tool, not of the specification.

Aligning the naming¶

So that the generated packages match the packages from Myra, pass the namespace and the package name as additional properties:

openapi-generator-cli generate -i openapi.yaml -g python \
  --additional-properties=invokerPackage=Myrasec\\EuCaptcha,packageName=eucaptcha,library=httpx \
  -o python

For Java, Myra uses the following properties:

Variant	Additional properties
`java-resttemplate`	`packageName=eucaptcha,groupId=com.myrasec,invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,modelPackage=com.myrasec.client.model,library=resttemplate`
`java-webclient`	`packageName=eucaptcha,groupId=com.myrasec,invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,modelPackage=com.myrasec.client.model,library=webclient`
`java-springboot3`	`packageName=eucaptcha,groupId=com.myrasec,invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,modelPackage=com.myrasec.client.model,library=webclient,useSpringBoot3=true,useJakartaEe=true`

All three variants use the java generator. See Java.

Using the generated client¶

For the POST /verify endpoint, the generator makes the verifyClientToken operation. The names in the destination language follow the rules of the applicable generator, but the structure of the request and of the answer stays the same:

Field of the request	Description
`sitekey`	Public sitekey from the Details view.
`secret`	Secret belonging to the sitekey.
`client_ip`	Actual IP address of the visitor.
`client_token`	Token from `verify.js`.
`client_user_agent`	`User-Agent` header of the request.

See Verify a client token.

Warning

In the answer, always also read the train field. If it has the true value, no verification occurred. See Configuring a sitekey.

The generated client does the server-side verification. Add the widget in the page with the form to be protected unchanged. See HTML and JavaScript.