Try microservice via GUI

Phonexia microservices are delivered as Docker images with a gRPC interface. This interface is the best choice for developers/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 a official Documentation on ➡️🔗**Using the gRPC request interface** ⬅️.
Documentation will guide you through

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

Basic notes

• Postman cannot work with files at this time - speaking about payload - meaning that all payload (e.g. audio file) must be converted to base64 format before sending in message
  • 08/2023 it is 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 - no size limitation. Keep in mind you must adhere to the message size limitations, see Good to know and section below.
• No limit on the request/outgoing message size
  • note that incoming message is often limited on gRPC server side with default 4MB
• You can now configure Maximum response message size under gRPC request settings, see link

caution

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

Using Postman

Following list contain overview of steps for communication with 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 to the URL)

   

4. Use server reflection to obtain 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 handy feature which will prepare example message for you. See button below message body text box.
   Notice also Documentation section on ride side of screen. This section help you write and understand 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 feature which generate a example message based method definition with random data.
This comes handy anytime you want to construct new message - only thing you need to change are random message values.

Example voiceprint extraction

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

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

1. Prepare audio data - Postman require 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 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 limit set by Postman, I needed to fit into default gRPC 4MB message limit, so chunks of this size worked for me
   • each line will represent certain part of audio
   • each line will be sent in separate message in opened stream
5. Open Postman and configure request - see Using Postman
6. Select method Extract
7. Prepare message
   • generate structure of message using Use Example Message
   • replace content field with first line of base64 encoded audio data from your text editor
8. Invoke request
9. Send message
10. Repeat following steps until all data from your text editor are sent
    • prepare message
      • generate structure of message using Use Example Message
      • replace content field with next line of base64 encoded audio data from your text editor - keep order of your data, send line by line
    • send message

      

11. End stream

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

Warthog

danger

Warthog is open-sourced repository with just one maintainer which brings uncertainty in future development and support. At the same time comes with certain instability while using it.
Therefore we cannot recommend using it.

Nevertheless it seems to be the only stable tool at a time which allows working directly with files, thats why it is mentioned here.

Warthog is a cross platform gRPC GUI client, see its GitHub project

Basic notes

• Works with files, no need to convert to base64. In fact base64 data are not supported on input at all.
• Input data size is limited to 4MB

caution

Currently, 08/2023 - Warthog Win/Lin client - version 0.5.2 - contains bug connected to configuration of secure communication - see Trusted root cert is needed even when insecure is used.

Workaround is easy:

• toggle Skip server certificate and domain verification (insecure)
• put any string in Text box Trusted root certificate(s)

Using Warthog

Setup Workspace

1. Create New Workspace
2. Fill in interactive form
   • gRPC server address
     • must contain port
     • must not contain any protocol prefix - see Good to know
   • toggle Use reflection to determine the RPC schema - this option will allow automatic loading of service definition
   • open TLS tab and toggle Skip server certificate and domain verification (insecure)
     • NOTE -> currently is known issue in TLS settings, see caution admonition above for more information
3. Save
   if Form missing any information it will highlight missing information using red color
   • after saving, New Workspace window will close and server definition should automatically load

Sent a request

1. Select method
2. Prepare request message
3. Sent request - big green "play" button

Good to know

• URL used in GUI clients - correct format of URL is voiceprint-extraction.phonexia.com:443
  • clients usually don't accept protocol prefix in URL - e.g. grpc://, https://
• While communicating via gRPC the default maximum message size is 4MB. Which is widely accepted and implemented standard in publicly available software.
• Overall size of (audio) file sent to 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 gRPC server side with default 4MB