Skip to main content
Version: 3.0.0

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
  • 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

    Postman create 'New Workspace'

  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)

    Postman secure communication

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

    Postman configure server reflection

  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.

    Postman request message definition and Documentation section

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

    Postman responses

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

      Postman sending messages to open stream

  11. End stream

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

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