Guides
Learn More about Newline

OpenAPI Guide

Using the OpenAPI Specification

Newline provides an OpenAPI specification that describes our API endpoints, request and response formats, authentication methods, and schemas in a machine‑readable format. This specification allows developers to explore the API, generate client SDKs, and integrate with tooling such as Postman or Swagger UI.

This guide explains what the /openapi page is, why it exists, and how you can use the OpenAPI spec effectively during development.

What Is the /openapi Page?

The /openapi page hosts Newline’s OpenAPI specification file, which is automatically generated from our API definitions.

You can access it here:

The page itself may appear minimal because it primarily provides access to the raw specification file. That file is intended to be consumed by tools, not read manually.

Why the OpenAPI Specification Exists

The OpenAPI specification enables you to:

  • Explore available API endpoints in a structured way
  • Understand request and response schemas
  • Import the full API into tools like Postman or Swagger UI
  • Generate client SDKs for your preferred programming language
  • Keep your local API tooling in sync with the latest Newline API definitions

Rather than relying on hand‑coded clients or manually updating collections, the OpenAPI spec acts as a single source of truth.

Downloading the OpenAPI Specification

To download the specification file directly:

  1. Visit the /openapi page.
  2. Download the file named newline-platform-api.json.
  3. Save it locally for use with your preferred tooling.

You can also reference the file directly by URL in tools that support importing OpenAPI specs from a remote source.

Using the OpenAPI Spec in Postman

You can import the OpenAPI specification into Postman to create a ready‑to‑use collection of Newline API requests.

Steps

  1. Open Postman.
  2. Click Import.
  3. Choose one of the following:
    • Upload the downloaded newline-platform-api.json file, or
    • Paste the direct URL to the OpenAPI JSON.
  4. Complete the import.

Postman will automatically generate:

  • Organized request collections
  • Request parameters
  • Example request bodies (where available)

Tip: You must still configure authentication (such as API keys or tokens) before sending requests.

Viewing the API with Swagger UI

Swagger UI provides an interactive, web‑based way to explore and test the API using the OpenAPI specification.

Option 1: Hosted Swagger UI

  1. Open a Swagger UI instance (self‑hosted or public).
  2. Load the OpenAPI spec by:
    • Uploading the JSON file, or
    • Providing the direct URL to newline-platform-api.json.
  3. Explore endpoints, schemas, and example requests.

Option 2: Local Swagger UI

If you run Swagger UI locally, configure it to point to the OpenAPI JSON file during startup.

Generating SDKs from the OpenAPI Spec

You can use OpenAPI‑compatible tools to generate client SDKs for many programming languages.

Example: OpenAPI Generator

openapi-generator-cli generate \
  -i newline-platform-api.json \
  -g python \
  -o newline-api-client

Example: Swagger Codegen

swagger-codegen generate \
  -i newline-platform-api.json \
  -l java \
  -o newline-api-client
``

Generated SDKs can help:

  • Reduce boilerplate code
  • Enforce schema correctness
  • Speed up integration development
🚧

Important Note: Generated SDKs may require customization to align with your application’s authentication, retry logic, or error‑handling patterns.

Keeping Your Tooling Up to Date

Because the OpenAPI specification is automatically generated, it may change over time as the API evolves. We recommend:

  • Re‑importing or refreshing the spec periodically
  • Regenerating SDKs after major API updates
  • Treating the OpenAPI spec as a living artifact rather than a one‑time setup

Updated 21 days ago