Link

C++

Table of contents

  1. Overview
  2. Run api init
  3. Configure api start task
  4. Give Optic the ability to start your API on a port it controls
    1. CppRestSDK SupportedRequires Code Change
    2. Pistache.io SupportedRequires Code Change
  5. Run api check to verify integration

Overview

By observing your API traffic, Optic learns the API contract, detects whenever the API’s behavior changes, and helps you test the API.

The goal of this tutorial is help you configure the Optic CLI to start your API and monitor the traffic from your C++ development environment. Once complete, you’ll invoke your application directly with Optic’s api command.

# your original start command
./application
# is substituted for Optic's start command
api start

Run api init

First, open a terminal and navigate to an API project. Your project will need to be runnable from this directory without any special permissions. Then run:

api init

alt text

After running api init Optic will add an optic.yml which:

Note The optic.yml file and the .optic folder should both be checked into version control.

Configure api start task

Now it’s time to show Optic how to start your API. Once completed you’ll be able to run your API using Optic’s api start command.

Open the optic.yml file in your favorite text editor and change the command and baseUrl fields:

optic.yml
name: Demo API
tasks:
  start:
    command: ./application
    baseUrl: http://localhost:4000

command - the command used to start your API server. It MUST:

  • Start a long-running process (your API) that stays running until exited
  • Be runnable from the same directory as the optic.yml file w/o any special permissions

baseUrl - the URL where you want the API to be accessible locally. It MUST:

  • Be on a port/hostname that doesn’t require special permissions to bind to (e.g. port 1024 and up) It SHOULD:
  • Be the same URL you use for local development today, that way the API consumers don’t need to be updated.

Give Optic the ability to start your API on a port it controls

Now you need to update your start command or code so that your API starts on the port Optic assigns it via the OPTIC_API_PORT environment variable.

This usually requires one of the following:

  • Updating 1-3 lines of code in your project
  • A flag to be passed into your start command that sets the API port to OPTIC_API_PORT

Look below for examples of how to make this change in your API framework:


CppRestSDK SupportedRequires Code Change

Simply modify your Http::Endpoint address to check for Optic’s environment variable first!

Before


utility::string_t port = U("5000");

utility::string_t address = U("http://127.0.0.1:");
address.append(port);
on_initialize(address);

After

std::string portStr = "5000";
if (getenv("OPTIC_API_PORT")) {
    portStr =  getenv ("OPTIC_API_PORT");
}
utility::string_t port = U(portStr);

utility::string_t address = U("http://127.0.0.1:");
address.append(port);

Pistache.io SupportedRequires Code Change

Simply modify your Http::Endpoint address to check for Optic’s environment variable first!

Before

int main() {
    Pistache::Address addr(Pistache::Ipv4::any(), Pistache::Port(8000));
    auto opts = Pistache::Http::Endpoint::options()
        .threads(1);

    Http::Endpoint server(addr);
    server.init(opts);
    server.setHandler(Http::make_handler<HelloHandler>());
    server.serve();
}

After

#include <stdlib.h>
#include <string>
...

int main() {
    int port = 8000;
    if (getenv("OPTIC_API_PORT")) {
            std::string s = getenv ("OPTIC_API_PORT");
            port = std::stoi(s);
    }
    Pistache::Address addr(Pistache::Ipv4::any(), Pistache::Port(port));
    auto opts = Pistache::Http::Endpoint::options()
        .threads(1);

    Http::Endpoint server(addr);
    server.init(opts);
    server.setHandler(Http::make_handler<HelloHandler>());
    server.serve();
}

Run api check to verify integration

Now it’s time to test that you have set up Optic correctly. The Optic CLI has a check command for testing the integration one step at a time to help diagnose any problems.

Here’s an example of running api check start with a working integration:

alt text

Now run the command in your project:

api check start

If Optic detects any issues with your API, it will provide a link to a fix in our documentation.

Need more help? Schedule some time to meet the maintainers and dig into your setup, or search GitHub Issues for your error, and open a new issue if nothing relevant returns.


All Done! Nice Work

Now that Optic is integrated, it’s time to document your API.

Start Documenting