Try Microservice via GUI

Phonexia microservices are delivered as Docker images with a gRPC interface. This interface is the best choice for developers or technically skilled individuals who wish to integrate it into their software.

However, if you prefer to try the microservice manually, there are many publicly available CLI or GUI tools, as well as language-specific frameworks that you can use. You can find an overview of these tools here, and those that support server reflection might be the most helpful.

Let's take a closer look at some GUI options.

Postman

Postman is an API platform for building and using APIs, see About Postman

Recommendation

Before starting using Postman with gRPC, consult the official documentation on ➡️🔗**Using the gRPC request interface** ⬅️.
The documentation will guide you through

• Postman GUI for gRPC
• gRPC concepts and their implementation in Postman

Basic notes

• Postman cannot work with files at this time (regarding payload), meaning that all payload (e.g., audio files) must be converted to base64 format before sending in a message.
  • As of 08/2023, it is an open ticket to add this feature Add support for gRPC client streaming from a file · Issue #11287.
• It is possible to process big audio files using Postman with no size limitation. Keep in mind you must adhere to the message size limitations. See Good to know and the section below.
• No limit on the request/outgoing message size.
  • note that the incoming message is often limited on the gRPC server side with default 4MB.
• You can now configure Maximum response message size under gRPC request settings, see link.

caution

Currently, as of 08/2023 - Postman Win/Lin client version - June 2023 (v10.15) - allows only sending ~ 3MB now. This seems to be a bug.

Using Postman

Following list contains an overview of steps for communication with a gRPC service using Postman.

1. Create new Request

   

2. Enter URL - URL should not contain any protocol prefix - see Good to know
3. Secure communication - enable TLS, if needed (see the Lock symbol to the left of the URL)

   

4. Use server reflection to obtain the service definition - this step should be automatic, if not, change in configuration

   

5. Select a method (see screenshot above)
6. Prepare request message, if needed
   Use Example Message is a handy feature that will prepare an example message for you. See the button below the message body text box.
   Notice also the Documentation section on the right side of the screen. This section helps you write and understand the message.

   

7. Invoke request (based on method type, send one or more messages)
8. Check the results and close the stream, if needed

   

Tip request message examples

Postman offers a feature that generates an example message based on the method definition with random data.
This is handy anytime you want to construct a new message - the only thing you need to change are random message values.

Example voiceprint extraction

The following example will show you how to extract a voiceprint from audio using the Phonexia Speaker identification microservice.

In this example I will use an audio file bigger than 4MB (the default limit, see Good to know), so I will need to split it into multiple messages while communicating with the service. This brings higher complexity to the example and at the same time helps illustrate the whole concept of the functionality.

1. Prepare audio data - Postman requires base64 representation of audio
2. Convert audio file to base64 in your favorite tool, I will use https://base64.guru/converter/encode/audio.
3. Copy the base64 data into your favorite text editor.
4. Split this one-liner into several lines - each line should have ~950 000 symbols.
   • 950 000 symbols is not a limit set by Postman, I needed to fit into the default gRPC 4MB message limit, so chunks of this size worked for me.
   • Each line will represent a certain part of the audio.
   • Each line will be sent in a separate message in the open stream.
5. Open Postman and configure request - see Using Postman
6. Select method Extract
7. Prepare message.
   • Generate the structure of the message using Use Example Message.
   • Replace the content field with the first line of base64 encoded audio data from your text editor.
8. Invoke the request.
9. Send the message.
10. Repeat the following steps until all data from your text editor is sent.
    • Prepare the message.
      • Generate the structure of the message using Use Example Message.
      • Replace the content field with the next line of base64 encoded audio data from your text editor - keep the order of your data, sending line by line.
    • Send the message:

      

11. End the stream.

Results should be received after a few seconds - see the bottom of the Postman window, section Responses.

Good to know

• URL used in GUI clients - the correct format of URL is voiceprint-extraction.phonexia.com:443
  • Clients usually don't accept protocol prefix in the URL, such as grpc:// or https://.
• While communicating via gRPC the default maximum message size is 4MB, which is a widely accepted and implemented standard in publicly available software.
• Overall size of an (audio) file sent to the service is not limited theoretically, but in default configuration (message size 4MB) you cannot sent whole audio bigger then limit in one message. It is necessary to open stream and send audio in parts one by one, each part in different message.
  • Keep in mind that incoming message if often limited on the gRPC server side with a default 4MB.