The new stable release of Remoting SDK and Data Abstract is out now!


In our previous post, we looked at the updated Service Tester, one of the highlights of this release. This time, we're focusing on another improvement: better support for REST APIs.

Your REST API can now use Unicode names on both .NET and Delphi, so your types and fields can carry the names your business uses.

Name a structure "Партнер", give it fields called "Händlername", "AñoFundación" and "会社名". Swagger shows those names exactly as you wrote them.

Three languages, one structure

Our demo server is an ordinary order service, and the supplier of a product is described the way a team in three countries would describe it: a German trade name, the year the company was founded and the company name in Japanese, all in one structure with a Cyrillic name.

There is nothing to switch on. HttpApi publishes this structure the same way it publishes any other type.

A valid description, with your names in it

Ask the server for /api and it hands you an OpenAPI description built from your RODL. Give that address to Swagger Editor, and the document opens without a single error.

The description our server produced, open in Swagger Editor, with the field names from the RODL.

A valid description is what everything else stands on. Swagger UI, code generators and API gateways all read the same document.

Every operation shows what it returns

Open any operation, and Swagger shows the shape of its answer before you call it. The fields are named the way you named them.

GET /orders/template: the example answer, with the supplier and its fields in three languages.

Anyone who calls your server knows what each call returns before writing a single line of code, without reading your RODL or asking you.

Your types keep their names

The Models section lists every structure the API uses. "Партнер" is there under its own name, with its fields, their types and the documentation you wrote in the RODL.

The Models section: a Cyrillic name, not a code standing in for it.
💡
If you open the raw document, you will see the name of such a type written as a code in a few places. Links inside an OpenAPI document must be plain text, and the code keeps them valid. The name people see is the one you gave it.

Try it out

Press Try it out, then Execute. The call goes to your server, and the answer comes back as text you can read.

A real answer from our server: "Nordwind GmbH", "北風商会", "Гамбург". Every character is the character itself.

The answer is plain UTF-8, and the header says so. Swagger, your browser, your logs and any HTTP tool show it as it is, with no \u041f in sight.

To call the server from the browser, turn on cross-origin requests on the channel and on the dispatcher:

channel.SendCrossOriginHeader = true;
apiDispatcher.AllowCORSRequests = true;

Send it back

It works the other way too. Change the values in the request body, write them in any language, and send them. The server gets them as they are.

POST /orders/echo: we changed the supplier in the request, and the server returned the order exactly as it was received.

And this is what our server logged when the request came in:

Lines[0].Product.Партнер.Händlername = "Südwind Handel AG" (17 chars)
Lines[0].Product.Партнер.AñoFundación = 1994
Lines[0].Product.Партнер.会社名 = "南風商事" (4 chars)
Lines[0].Product.Партнер.Address.City = "Гамбург" (7 chars)
Lines[0].Product.Партнер.Address.Street = "Менкебергштрассе, 7" (19 chars)

Four characters for "南風商事", not twelve bytes. The server works with your text, not with its encoding.

Since build .1629

  • Valid OpenAPI for any name: types and fields with Unicode names produce a valid description.
  • Real names in Swagger: a type with a Unicode name is shown under its own name.
  • Readable JSON: HttpApi answers carry the characters themselves, not \u escapes.
  • Try it out works: with CORS enabled, every API answer carries the CORS header, so Swagger UI can call your server from the browser.
  • Unicode names in messages: BinMessage and PostMessage carry type and field names in any language.
  • Names in any language: services, methods, structures and fields in RODL can now use any characters on .NET and Delphi.
  • Query strings in file dispatchers: your custom request handler now receives the query string of the request.
  • Win64x for C++Builder: Remoting SDK and Data Abstract packages support the Win64x target in RAD Studio 12 and 13.
  • Service Builder and Service Tester speak Unicode: design and test services whose types and fields are named in any language. Service Tester also handles every type at any depth – read more in our previous post.

Build .1629 is out now. (Remoting SDK | Data Abstract)