Skip to content

Commit 2d53452

Browse files
fabriziofioruccifabriziofiorucci
authored
REST API v4.2 (#37)
* 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
1 parent a9d0226 commit 2d53452

33 files changed

+3123
-2721
lines changed

‎.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ Thumbs.db
2020
=======
2121
/.idea/
2222
/src/__pycache__/
23-
/src/v3_1/__pycache__/
23+
/src/v4_0/__pycache__/
24+
/src/v4_1/__pycache__/
25+
/src/v4_2/__pycache__/
2426
/contrib/devportal/redocly/src/__pycache__/
2527
/venv/

‎FEATURES.md

Lines changed: 160 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,173 @@
22

33
### NGINX `http` and `stream` servers
44

5-
| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
6-
|----------------------------|----------|----------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
7-
| Upstreams | CRUD | CRUD | CRUD | <li>Snippets supported: static and from source of truth</li> |
8-
| HTTP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`http`, `servers`, `locations`): static and from source of truth</li> |
9-
| TCP/UDP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`streams`, `servers`): static and from source of truth</li> |
10-
| TLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
11-
| mTLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
12-
| JWT client authentication | | X | X | <li>Static JWT key</li><li>JWT fetched from URL</li> |
13-
| Upstream authentication | | | X | <li>Bearer token</li><li>HTTP header</li> |
14-
| Rate limiting | X | X | X | |
15-
| Active healthchecks | X | X | X | |
16-
| Cookie-based stickiness | X | X | X | |
17-
| Maps | X | X | X | |
18-
| NGINX Plus REST API access | X | X | X | |
19-
| 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> |
5+
| Feature | API v4.0 | API v4.1 | API v4.2 | Notes |
6+
|----------------------------|----------|----------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
7+
| Upstreams | CRUD | CRUD | CRUD | <li>Snippets supported: static and from source of truth</li> |
8+
| HTTP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`http`, `servers`, `locations`): static and from source of truth</li> |
9+
| TCP/UDP servers | CRUD | CRUD | CRUD | <li>Snippets supported (`streams`, `servers`): static and from source of truth</li> |
10+
| TLS | CRUD | CRUD | CRUD | <li>Certificates and keys can be dynamically fetched from source of truth</li> |
11+
| Client authentication | X | X | X | See [client authentication profiles](#Client-authentication-profiles) |
12+
| Server authentication | X | X | X | See [server authentication profiles](#Upstream-and-Source-of-truth-authentication-profiles) |
13+
| Rate limiting | X | X | X | |
14+
| Active healthchecks | X | X | X | |
15+
| Cookie-based stickiness | X | X | X | |
16+
| HTTP headers manipulation | | | X | <li>To server: set, delete</li><li>To client: add, delete, replace</li> |
17+
| Maps | X | X | X | |
18+
| NGINX Plus REST API access | X | X | X | |
19+
| 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> |
2020

2121
### API Gateway
2222

23-
| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
24-
|----------------------------------------------|----------|----------|----------|--------------------------------------------------------------------------------------|
25-
| Configuration generation from OpenAPI schema | X | X | X | |
26-
| HTTP methods enforcement | X | X | X | |
27-
| per-URI rate limiting | X | X | X | |
28-
| 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> |
23+
| Feature | API v4.0 | API v4.1 | API v4.2 | Notes |
24+
|----------------------------------------------|----------|----------|----------|-------------------------------------------------------------------------------------------|
25+
| Configuration generation from OpenAPI schema | X | X | X | |
26+
| HTTP methods enforcement | X | X | X | |
27+
| per-URI rate limiting | X | X | X | |
28+
| per-URI client authentication | X | X | X | <li>Static JWT key</li><li>JWT key fetched from URL</li><li>Bearer token</li> |
2929

3030
### API Gateway - Developer Portal
3131

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

36-
### Source of truth
36+
### Client authentication
3737

38-
| Feature | API v3.1 | API v4.0 | API v4.1 | Notes |
39-
|--------------------------------------|----------|----------|----------|-------|
40-
| HTTP header-based authentication | | | X | |
41-
| Bearer token authentication | | | X | |
38+
| Type | Description | API v4.0 | API v4.1 | API v4.2 | Notes |
39+
|------|----------------------|----------|---------|----------|-------------------------------------|
40+
| jwt | Java Web Token (JWT) | | X | X | |
41+
| mtls | Mutual TLS | X | X | X | <li>Supported for HTTP servers</li> |
42+
43+
#### Examples
44+
45+
Client-side authentication profiles to be defined under `.declaration.http.authentication.client[]`
46+
47+
- jwt client authentication profile
48+
49+
```json
50+
{
51+
"name": "<PROFILE_NAME>",
52+
"type": "jwt",
53+
"jwt": {
54+
"realm": "<JWT_AUTHENTICATION_REALM>",
55+
"key": "<JWT_KEY>|<JWT_KEY_URL>",
56+
"cachetime": <JWT_KEY_CACHETIME_IN_SECONDS>
57+
}
58+
}
59+
```
60+
61+
- mTLS client authentication profile
62+
63+
```json
64+
{
65+
"name": "<PROFILE_NAME>",
66+
"type": "mtls",
67+
"mtls": {
68+
"enabled": "<on|off|optional|optional_no_ca>",
69+
"client_certificates": "<CLIENT_CERTIFICATES_OBJECT_NAME>"
70+
}
71+
}
72+
```
73+
74+
### Upstream and Source of truth authentication
75+
76+
| Type | Description | API v4.0 | API v4.1 | API v4.2 | Notes |
77+
|--------------|----------------------------------------------|----------|----------|----------|----------------------------------------------------------------------------------------|
78+
| Bearer token | Authentication token as Authorization Bearer | | X | X | `Bearer` Authorization header is injected in requests to upstreams and source of truth |
79+
| Basic Auth | Authentication token as Authorization Basic | | | X | `Basic` Authorization header is injected in requests to upstreams and source of truth |
80+
| HTTP header | Authentication token in custom HTTP header | | X | X | HTTP header is injected in requests to upstreams and source of truth |
81+
82+
#### Examples
83+
84+
Server-side authentication profiles to be defined under `.declaration.http.authentication.client[]`
85+
86+
- Bearer token authentication profile
87+
88+
```json
89+
{
90+
"name": "<PROFILE_NAME>",
91+
"type": "token",
92+
"token": {
93+
"type": "bearer",
94+
"token": "<AUTHENTICATION_TOKEN>"
95+
}
96+
}
97+
```
98+
99+
- Basic authentication profile
100+
101+
```json
102+
{
103+
"name": "<PROFILE_NAME>",
104+
"type": "token",
105+
"token": {
106+
"type": "basic",
107+
"username": "<AUTHENTICATION_USERNAME>",
108+
"password": "<BASE64_ENCODED_PASSWORD>"
109+
}
110+
}
111+
```
112+
113+
- HTTP header authentication profile
114+
115+
```json
116+
{
117+
"name": "<PROFILE_NAME>",
118+
"type": "token",
119+
"token": {
120+
"type": "header",
121+
"token": "<AUTHENTICATION_TOKEN>",
122+
"location": "<HTTP_HEADER_NAME>"
123+
}
124+
}
125+
```
126+
127+
### HTTP Headers manipulation
128+
129+
| Type | API v4.0 | API v4.1 | API v4.2 | Notes |
130+
|-----------------------------|----------|----------|----------|------------------------------------------------------------------------------------------------------------------------------|
131+
| Request (client to server) | | | X | <li>`set` - new header injection</li><li>`delete` - client header removal</li> |
132+
| Response (server to client) | | | X | <li>`add` - new header injection</li><li>`delete` - server header removal</li><li>`replace` - server header replacement</li> |
133+
134+
#### Examples
135+
136+
To be defined under `.declaration.http.servers[].headers` and/or `.declaration.http.servers[].location[]`
137+
138+
```json
139+
"headers": {
140+
"to_server": {
141+
"set": [
142+
{
143+
"name": "<HTTP_HEADER_NAME>",
144+
"value": "<VALUE_OR_NGINX_VARIABLE>"
145+
},
146+
...
147+
],
148+
"delete": [
149+
"<HTTP_HEADER_NAME>",
150+
...
151+
]
152+
},
153+
"to_client": {
154+
"add": [
155+
{
156+
"name": "<HTTP_HEADER_NAME>",
157+
"value": "<VALUE_OR_NGINX_VARIABLE>"
158+
},
159+
...
160+
],
161+
"delete": [
162+
"<HTTP_HEADER_NAME>",
163+
...
164+
],
165+
"replace": [
166+
{
167+
"name": "<HTTP_HEADER_NAME>",
168+
"value": "<VALUE_OR_NGINX_VARIABLE>"
169+
},
170+
...
171+
]
172+
}
173+
}
174+
```

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,9 @@ See the [features list](/FEATURES.md)
140140

141141
Usage details and JSON schema are available here:
142142

143-
- [API v4.1](/USAGE-v4.1.md) - latest
143+
- [API v4.2](/USAGE-v4.2.md) - latest
144+
- [API v4.1](/USAGE-v4.1.md)
144145
- [API v4.0](/USAGE-v4.0.md)
145-
- [API v3.1](/USAGE-v3.1.md)
146146

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

0 commit comments

Comments
 (0)