Skip to content

Commit

Permalink
REST API v4.2 (#37)
Browse files Browse the repository at this point in the history 
* API v4.2 alpha - 2024020101 commit

* API v4.2 alpha - 2024020102 commit

* API v4.2 alpha - 2024020103 commit

* API v4.2 alpha - 2024020104 commit

* API v4.2 alpha - 2024020104 commit

* API v4.2 alpha - 2024020105 commit

* 20240207-01 Commit

* 20240207-03 Commit

* Delete src/Contrib/__pycache__ directory

* 20240207-05 Commit

* 20240208-01 Commit

* 20240208-02 Commit
  • Loading branch information
@fabriziofiorucci
fabriziofiorucci authored Feb 8, 2024
1 parent a9d0226 commit 2d53452
Show file tree
Hide file tree
Showing 33 changed files with 3,123 additions and 2,721 deletions.
4 changes: 3 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ Thumbs.db
=======
/.idea/
/src/__pycache__/
/src/v3_1/__pycache__/
/src/v4_0/__pycache__/
/src/v4_1/__pycache__/
/src/v4_2/__pycache__/
/contrib/devportal/redocly/src/__pycache__/
/venv/
187 changes: 160 additions & 27 deletions FEATURES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,173 @@

### NGINX `http` and `stream` servers

| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
|----------------------------|----------|----------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Upstreams | CRUD | CRUD | CRUD | <li>Snippets supported: static and from source of truth</li> |
| HTTP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`http`, `servers`, `locations`): static and from source of truth</li> |
| TCP/UDP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`streams`, `servers`): static and from source of truth</li> |
| TLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
| mTLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
| JWT client authentication | | X | X | <li>Static JWT key</li><li>JWT fetched from URL</li> |
| Upstream authentication | | | X | <li>Bearer token</li><li>HTTP header</li> |
| Rate limiting | X | X | X | |
| Active healthchecks | X | X | X | |
| Cookie-based stickiness | X | X | X | |
| Maps | X | X | X | |
| NGINX Plus REST API access | X | X | X | |
| NGINX App Protect WAF | X | X | X | <li>Per-policy CRUD at `server` and `location` level</li><li>Support for dataplane-based bundle compilation</li><li>Security policies can be fetched from source of truth</li> |
| Feature | API v4.0 | API v4.1 | API v4.2 | Notes |
|----------------------------|----------|----------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Upstreams | CRUD | CRUD | CRUD | <li>Snippets supported: static and from source of truth</li> |
| HTTP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`http`, `servers`, `locations`): static and from source of truth</li> |
| TCP/UDP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`streams`, `servers`): static and from source of truth</li> |
| TLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
| Client authentication | X | X | X | See [client authentication profiles](#Client-authentication-profiles) |
| Server authentication | X | X | X | See [server authentication profiles](#Upstream-and-Source-of-truth-authentication-profiles) |
| Rate limiting | X | X | X | |
| Active healthchecks | X | X | X | |
| Cookie-based stickiness | X | X | X | |
| HTTP headers manipulation | | | X | <li>To server: set, delete</li><li>To client: add, delete, replace</li> |
| Maps | X | X | X | |
| NGINX Plus REST API access | X | X | X | |
| NGINX App Protect WAF | X | X | X | <li>Per-policy CRUD at `server` and `location` level</li><li>Support for dataplane-based bundle compilation</li><li>Security policies can be fetched from source of truth</li> |

### API Gateway

| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
|----------------------------------------------|----------|----------|----------|--------------------------------------------------------------------------------------|
| Configuration generation from OpenAPI schema | X | X | X | |
| HTTP methods enforcement | X | X | X | |
| per-URI rate limiting | X | X | X | |
| per-URI JWT authentication | X | X | X | <li>Static JWT key</li><li>JWT fetched from URL</li><li>Bearer token (API v4.1)</li> |
| Feature | API v4.0 | API v4.1 | API v4.2 | Notes |
|----------------------------------------------|----------|----------|----------|-------------------------------------------------------------------------------------------|
| Configuration generation from OpenAPI schema | X | X | X | |
| HTTP methods enforcement | X | X | X | |
| per-URI rate limiting | X | X | X | |
| per-URI client authentication | X | X | X | <li>Static JWT key</li><li>JWT key fetched from URL</li><li>Bearer token</li> |

### API Gateway - Developer Portal

| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
| Feature | API v4.0 | API v4.1 | API v4.2 | Notes |
|-------------------------------------------------|----------|----------|----------|---------------------------|
| Developer Portal generation from OpenAPI schema | X | X | X | <li>Based on Redocly</li> |

### Source of truth
### Client authentication

| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
|--------------------------------------|----------|----------|----------|-------|
| HTTP header-based authentication | | | X | |
| Bearer token authentication | | | X | |
| Type | Description | API v4.0 | API v4.1 | API v4.2 | Notes |
|------|----------------------|----------|---------|----------|-------------------------------------|
| jwt | Java Web Token (JWT) | | X | X | |
| mtls | Mutual TLS | X | X | X | <li>Supported for HTTP servers</li> |

#### Examples

Client-side authentication profiles to be defined under `.declaration.http.authentication.client[]`

- jwt client authentication profile

```json
{
"name": "<PROFILE_NAME>",
"type": "jwt",
"jwt": {
"realm": "<JWT_AUTHENTICATION_REALM>",
"key": "<JWT_KEY>|<JWT_KEY_URL>",
"cachetime": <JWT_KEY_CACHETIME_IN_SECONDS>
}
}
```

- mTLS client authentication profile

```json
{
"name": "<PROFILE_NAME>",
"type": "mtls",
"mtls": {
"enabled": "<on|off|optional|optional_no_ca>",
"client_certificates": "<CLIENT_CERTIFICATES_OBJECT_NAME>"
}
}
```

### Upstream and Source of truth authentication

| Type | Description | API v4.0 | API v4.1 | API v4.2 | Notes |
|--------------|----------------------------------------------|----------|----------|----------|----------------------------------------------------------------------------------------|
| Bearer token | Authentication token as Authorization Bearer | | X | X | `Bearer` Authorization header is injected in requests to upstreams and source of truth |
| Basic Auth | Authentication token as Authorization Basic | | | X | `Basic` Authorization header is injected in requests to upstreams and source of truth |
| HTTP header | Authentication token in custom HTTP header | | X | X | HTTP header is injected in requests to upstreams and source of truth |

#### Examples

Server-side authentication profiles to be defined under `.declaration.http.authentication.client[]`

- Bearer token authentication profile

```json
{
"name": "<PROFILE_NAME>",
"type": "token",
"token": {
"type": "bearer",
"token": "<AUTHENTICATION_TOKEN>"
}
}
```

- Basic authentication profile

```json
{
"name": "<PROFILE_NAME>",
"type": "token",
"token": {
"type": "basic",
"username": "<AUTHENTICATION_USERNAME>",
"password": "<BASE64_ENCODED_PASSWORD>"
}
}
```

- HTTP header authentication profile

```json
{
"name": "<PROFILE_NAME>",
"type": "token",
"token": {
"type": "header",
"token": "<AUTHENTICATION_TOKEN>",
"location": "<HTTP_HEADER_NAME>"
}
}
```

### HTTP Headers manipulation

| Type | API v4.0 | API v4.1 | API v4.2 | Notes |
|-----------------------------|----------|----------|----------|------------------------------------------------------------------------------------------------------------------------------|
| Request (client to server) | | | X | <li>`set` - new header injection</li><li>`delete` - client header removal</li> |
| Response (server to client) | | | X | <li>`add` - new header injection</li><li>`delete` - server header removal</li><li>`replace` - server header replacement</li> |

#### Examples

To be defined under `.declaration.http.servers[].headers` and/or `.declaration.http.servers[].location[]`

```json
"headers": {
"to_server": {
"set": [
{
"name": "<HTTP_HEADER_NAME>",
"value": "<VALUE_OR_NGINX_VARIABLE>"
},
...
],
"delete": [
"<HTTP_HEADER_NAME>",
...
]
},
"to_client": {
"add": [
{
"name": "<HTTP_HEADER_NAME>",
"value": "<VALUE_OR_NGINX_VARIABLE>"
},
...
],
"delete": [
"<HTTP_HEADER_NAME>",
...
],
"replace": [
{
"name": "<HTTP_HEADER_NAME>",
"value": "<VALUE_OR_NGINX_VARIABLE>"
},
...
]
}
}
```
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,9 +140,9 @@ See the [features list](/FEATURES.md)

Usage details and JSON schema are available here:

- [API v4.1](/USAGE-v4.1.md) - latest
- [API v4.2](/USAGE-v4.2.md) - latest
- [API v4.1](/USAGE-v4.1.md)
- [API v4.0](/USAGE-v4.0.md)
- [API v3.1](/USAGE-v3.1.md)

A sample Postman collection and usage instructions can be found [here](/contrib/postman)

Expand Down
Loading

0 comments on commit 2d53452

Please sign in to comment.