پرش به مطلب اصلی

Getting Started with OrbNET APIs

Welcome to the OrbNET API Developer Guide! This section will help you get up and running with OrbNET’s GraphQL APIs, enabling seamless integration with your applications. Whether you're building a new feature or integrating OrbNET into an existing system, this guide provides the foundational steps to get you started.

Introduction​

OrbNET’s backend is built with Java Spring, leveraging GraphQL for its API architecture. GraphQL offers a flexible and efficient way to interact with your data, allowing clients to request exactly what they need. This guide will walk you through the essential steps to authenticate and interact with OrbNET’s GraphQL APIs.

OrbVPN System Architecture​

This is a simplified system architecture chart of OrbVPN. You can explore the architecture in detail via the Miro board linked below.

View the Architecture​

Feel free to zoom in and navigate the different components of the system. This board provides a visual representation of how the backend and frontend components of OrbVPN interact, along with key integrations and services.

Prerequisites​

Before you begin, ensure you have the following:

  • OrbNET Account: An active account with API access permissions.
  • Development Environment: Set up with your preferred programming language (e.g., JavaScript, Python, Java).
  • GraphQL Client: Tools like GraphQL Playground or Postman for testing API requests.
  • Basic Knowledge of GraphQL: Familiarity with GraphQL queries and mutations.

Authentication​

To interact with OrbNET’s APIs, you must authenticate using the Login API. Authentication is handled via JSON Web Tokens (JWT), which must be included in the Authorization header of your requests.

Login API​

Endpoint:

POST https://orbnnet.com/graphql

GraphQL Mutation:

mutation Login($username: String!, $password: String!) {
  login(username: $username, password: $password) {
    token
    refreshToken
  }
}

Parameters:

  • username (String!): Your OrbNET username.
  • password (String!): Your OrbNET password.

Example Request:

{
  "query": "mutation Login($username: String!, $password: String!) { login(username: $username, password: $password) { token refreshToken } }",
  "variables": {
    "username": "your_username",
    "password": "your_password"
  }
}

Example Response:

{
  "data": {
    "login": {
      "token": "your_jwt_token",
      "refreshToken": "your_refresh_token"
    }
  }
}

Storing and Using Tokens​

  • Access Token (token): Use this JWT for authenticating your API requests. Include it in the Authorization header as follows:
Authorization: Bearer your_jwt_token
  • Refresh Token (refreshToken): Use this token to obtain a new access token when the current one expires.

Making API Requests​

Once authenticated, you can start making API requests to interact with OrbNET’s services.

Setting Up the Request​

  • Endpoint: All requests are sent to https://api.orbnnet.com/graphql.
  • Headers:
  • Content-Type: application/json
  • Authorization: Bearer your_jwt_token (for authenticated requests)

Example Query​

Fetch User Details​

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    createdAt
  }
}

Making API Requests​

Once authenticated, you can start making API requests to interact with OrbNET’s services.

Setting Up the Request

  • Endpoint: All requests are sent to https://orbnnet.com/graphql.
  • Headers:
  • Content-Type: application/json
  • Authorization: Bearer your_jwt_token (for authenticated requests)

Example Query​

Fetch User Details​

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    createdAt
  }
}

Example Request​

{
  "query": "query GetUser($id: ID!) { user(id: $id) { id name email createdAt } }",
  "variables": {
    "id": "user_id"
  }
}

Example Response​

{
  "data": {
    "user": {
      "id": "user_id",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "createdAt": "2023-01-01T00:00:00Z"
    }
  }
}

Handling Responses and Errors​

OrbNET APIs follow standard GraphQL response structures. It’s crucial to handle both successful responses and errors effectively.

Successful Response​

Contains a data field with the requested information.

{
  "data": {
    "user": {
      "id": "user_id",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "createdAt": "2023-01-01T00:00:00Z"
    }
  }
}

Error Response​

Contains an errors field with details about what went wrong.

{
  "errors": [
    {
      "message": "Invalid credentials",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["login"]
    }
  ],
  "data": null
}

Best Practices​

  • Always Check for Errors: Before processing the data field, verify if the errors field is present.
  • Handle Token Expiry: Implement logic to refresh tokens using the refreshToken when you receive authentication errors.
  • Validate Input: Ensure all required variables are provided and correctly formatted to minimize errors.

Development Tools​

To enhance your development workflow, consider using the following tools:

1. GraphQL Playground​

An interactive IDE for exploring GraphQL APIs. It allows you to write queries, mutations, and view responses in real-time.

2. Postman​

A versatile tool for testing APIs, including GraphQL endpoints.

  • Installation: Postman Download
  • Usage: Create a new POST request to https://api.orbnnet.com/graphql, set headers, and input your GraphQL queries.

3. Apollo Client​

A comprehensive state management library for JavaScript apps that makes it easy to manage data with GraphQL.

  • Documentation: Apollo Client Docs
  • Usage: Integrate Apollo Client into your React or other JavaScript frameworks to interact with OrbNET APIs seamlessly.