Environments

There are environments and base URLs for making API calls, one for production and the other for training, development, or testing (e.g. sandbox). As a developer, you can test with the sandbox APIs and then deploy to production by switching your integration to the production base URLs. The base URLs for the two APIs are as follows:

Understanding Environments in Software and APIs

In software and API development, environments are distinct settings where code is run, tested, and eventually deployed for use. Think of each environment as a separate "stage" that serves a specific purpose in the journey from development to final release.

By using multiple environments with consistent code across critical stages, software teams can develop, test, and release with confidence, ensuring that code is thoroughly vetted and optimized before it reaches end users.

1. Sandbox Environment

The sandbox is a safe testing ground—perfect for trying out new ideas, testing functionalities, and integrating with other systems. Since it typically mirrors the production environment, running the same version of the code, the sandbox provides a reliable setting for initial integration, integration testing, and experimenting with API functionality. Developers can test how systems interact, confirm compatibility, and ensure workflows function correctly before deploying to production.

This environment is commonly used for experimenting with API integrations, testing workflows, and evaluating code behavior without impacting live users or real data.

Benefits of the Sandbox Environment:

• Risk-Free Testing
  • Experiment without affecting real data or impacting production users.
• Consistency with Production
  • Runs the same code version as production minimizes surprises when deploying to live users.
• Initial Integration and Testing
  • Ideal for onboarding, initial API integrations and validating that connections and data flows work as expected before going live in production.
• Faster Iterations
  • Make and test changes quickly, gaining immediate feedback.
• Security
  • Avoid exposing sensitive data while testing, as sandbox environments often use dummy data.

2. Production Environment

Production is where the "real" action happens. It's the live environment where your software or API interacts with end users and real data. Here, every update, change, and interaction needs to be flawless, as it directly impacts the user experience.

With the same code version across sandbox and production, any issues discovered in sandbox can be reliably addressed, reducing unexpected outcomes during deployment.

Benefits of the Production Environment:

• Real-World Usage
  • The production environment is the real-world environment where the real users and live data interact.
• Reliability and Stability
  • The production environment is designed with high levels of security, uptime, and stability in mind.
• Performance Optimization
  • Performance monitoring and optimization can be accurately measured under real usage conditions.
• Seamless Transitions
  • Code parity with sandbox which reduces deployment risk, ensuring smoother releases.

Constructing API URLs

URLs to Shipwell API endpoints may be constructed by combining the environment's host with a basePath and the API endpoint's route.

The basePath will typically take one of two values, either "" (empty string) for newer APIs or /v2 for older APIs.

For example:

• https://sandbox-api.shipwell.com/v2/shipments as the URL for a sandbox List/Get Shipments endpoint is constructed using the following information:
  • {scheme} = "https" (aka HTTP protocol or scheme) is "https" (our APIs only support "https" for the scheme, so it does not need to be a true variable)
  • {environmentHost} = "sandbox-api.shipwell.com" is dependent on the environment [i.e. "sandbox-api.shipwell.com" (sandbox), "api.shipwell.com" (production), etc.]
  • {basePath} = "/v2" is dependent on the endpoint, but is typically "/v2" or "" (no base path for next generation endpoints like Orders )
  • {resourcePath} = "/shipments/ is dependent on the resource or endpoint

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments/"

String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/shipments/";

const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const targetUrl = `https://${host}${basePath}/shipments/`;

Versioning

Learn more about API versioning here.