1. REST API

To better understand APIs in the context of Ngenea Hub, let’s start with a quick overview of what an API is and its essential concepts.

An API (Application Programming Interface) is a set of rules and protocols that allows software applications to communicate with each other. APIs define how to request and send data, which functions are available, and what responses can be expected.

What are Remote APIs?

Remote APIs are APIs where the software making the request and the software providing the data are on different machines or different networks. These APIs work over the internet or a network, using tools like HTTP.

What are Web-Based APIs?

Web-based APIs are remote APIs that use web protocols like HTTP or HTTPS to communicate. They often send and receive data in formats like JSON. These APIs are widely used in websites and mobile apps to get or send data.

What are REST APIs?

REST (Representational State Transfer) APIs are a special kind of web-based API that follow a specific set of design rules. They use URLs to identify resources (like a user or a file) and HTTP methods like GET or POST to perform actions on those resources.

When is an API called RESTful?

An API is called RESTful when it follows the rules (constraints) of REST. It must behave in a certain predictable way, such as using HTTP properly and not storing client information on the server between requests.

What Are the Constraints that make an API REST?

• Stateless: Each request from a client to the server must contain all the information needed. The server doesn’t remember past requests.

• Client-Server Architecture: The system is split into clients (apps, browsers) and servers (data providers), and each focuses only on its role.

• Cacheable: Responses can be stored by the client to avoid repeating the same request.

• Uniform Interface: There is a standard way to access resources (like using GET to read data, POST to create).

• Layered System: The system can have layers (like security, load balancers) that the client doesn’t need to know about.

• Code on Demand (optional): Servers can send code (like JavaScript) to the client to run if needed.

How is JSON Related to API?

JSON (JavaScript Object Notation) is a simple format for organizing and exchanging data. When an app talks to an API, the API often replies with data in JSON format.

What is an OAuth Token?

An OAuth token is like a digital key that lets someone use a service without logging in every time.

HTTP Verbs vs CRUD Operations

HTTP Verb	CRUD Operation	Example Action
GET	Read	Get user details
POST	Create	Add a new blog post
PATCH	Update (partial)	Change only the email address
DELETE	Delete	Remove a user

Now, we’ll focus on understanding the APIs specifically for Ngenea Hub.

• 1.1. Authentication Methods
  • 1.1.1. Overview
  • 1.1.2. API Reference Location
  • 1.1.3. JWT Authentication - Using Curl
  • 1.1.4. Client Key Authentication
  • 1.1.5. Key Differences Between JWT and API Keys
  • 1.1.6. JWT Authentication - Using Swagger UI
  • 1.1.7. Generate a Client Key - Using Swagger UI
• 1.2. API Endpoints - User and Access Management
  • 1.2.1. Introduction
  • 1.2.2. API Reference Location
  • 1.2.3. Auth - Authentication
    • 1.2.3.1. GET /auth/clientkeys/
    • 1.2.3.2. GET /auth/clientkeys/{id}/
    • 1.2.3.3. DELETE /auth/clientkeys/{id}/
    • 1.2.3.4. GET /api/auth/token/publickey/
    • 1.2.3.5. POST /api/auth/token/verify/
  • 1.2.4. Users
    • 1.2.4.1. GET /users/
    • 1.2.4.2. POST /users/
    • 1.2.4.3. POST /users/change_password/
    • 1.2.4.4. GET /users/{username}/
    • 1.2.4.5. PATCH /users/{username}/
    • 1.2.4.6. DELETE /users/{username}/
    • 1.2.4.7. POST /users/{username}/activate/
    • 1.2.4.8. POST /users/{username}/deactivate/
  • 1.2.5. My Permissions
    • 1.2.5.1. GET /my-permissions/
  • 1.2.6. Permissions
    • 1.2.6.1. GET /permissions/
    • 1.2.6.2. GET /permissions/{id}/
  • 1.2.7. Groups
    • 1.2.7.1. GET /groups/
    • 1.2.7.2. POST /groups/
    • 1.2.7.3. GET /groups/{id}/
    • 1.2.7.4. PATCH /groups/{id}/
    • 1.2.7.5. DELETE /groups/{id}/
• 1.3. API Endpoint - Policies
  • 1.3.1. API Reference Location
  • 1.3.2. GET /policies/
  • 1.3.3. POST /policies/
  • 1.3.4. GET /policies/{id}/
  • 1.3.5. PATCH /policies/{id}/
  • 1.3.6. DELETE /policies/{id}/
    • 1.3.6.1. POST /policies/{id}/run/