Skip to content

Commit 7e8ba4f

Browse files
Bombardier-C-KramBombardier-C-Kram
committed
Improve examples
1 parent 9f51e17 commit 7e8ba4f

5 files changed

Lines changed: 175 additions & 87 deletions

File tree

‎docs/examples/authentication.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Authentication
2+
3+
These examples show how to configure authentication for APIs that require it. Credentials can be hardcoded or read from environment variables at request time using the `env:[VAR_NAME]` syntax[^1], so tokens are never embedded in source code.
4+
5+
[^1]: Environment variable substitution currently only applies to header values. Support for other parameter locations is planned.
6+
7+
## Bearer token
8+
9+
For APIs that use HTTP bearer authentication:
10+
11+
```apl
12+
config ← (
13+
baseUrl: 'https://api.example.com'
14+
security: (bearerToken: 'env:[API_TOKEN]')
15+
)
16+
client ← ⎕NEW Client config
17+
```
18+
19+
With `API_TOKEN` set in the environment:
20+
21+
```bash
22+
export API_TOKEN=my-secret-token
23+
```
24+
25+
Requests will include the header `Authorization: Bearer my-secret-token` automatically.
26+
27+
## API key
28+
29+
For APIs that use API key authentication:
30+
31+
```apl
32+
config ← (
33+
baseUrl: 'https://api.example.com'
34+
security: (apiKey: 'env:[API_KEY]')
35+
)
36+
client ← ⎕NEW Client config
37+
```
38+
39+
## Basic auth
40+
41+
For APIs that use HTTP basic authentication, provide both `username` and `password`:
42+
43+
!!! warning
44+
Environment variable substitution does not currently apply to basic auth credentials. `username` and `password` must be provided as literal strings.
45+
46+
```apl
47+
config ← (
48+
baseUrl: 'https://api.example.com'
49+
security: (
50+
username: 'alice'
51+
password: 'my-secret-password'
52+
)
53+
)
54+
client ← ⎕NEW Client config
55+
```
56+
57+
The credentials are Base64-encoded and sent as an `Authorization: Basic ...` header on every request.

‎docs/examples/debugging.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Debugging
2+
3+
## Inspecting requests without sending them
4+
5+
Mock mode lets you verify what the client would send before hitting a live server. Set `mock` to `1` in the config:
6+
7+
```apl
8+
config ← (
9+
baseUrl: 'https://petstore3.swagger.io/api/v3'
10+
mock: 1
11+
)
12+
client ← ⎕NEW Client config
13+
```
14+
15+
Calling an operation now returns the HttpCommand request object instead of a response:
16+
17+
```apl
18+
req ← client.pets.ShowPetById (petId: 42)
19+
req.URL
20+
https://petstore3.swagger.io/api/v3/pets/42
21+
req.Method
22+
GET
23+
```
24+
25+
This is useful for confirming that path parameters are substituted correctly, query strings are serialised as expected, and authentication headers are present.
26+
27+
## Printing requests to the session
28+
29+
For a lighter-weight option, enable debug mode after constructing the client:
30+
31+
```apl
32+
client.∆.Debug ← 1
33+
client.pets.ListPets ()
34+
```
35+
36+
This prints the raw HTTP request to the APL session before sending, and still returns the normal response. To turn it off:
37+
38+
```apl
39+
client.∆.Debug ← 0
40+
```
41+
42+
See [Mock mode](../generated-client/client.md#mock-mode) for the full range of `mock` values.

‎docs/examples/index.md‎

Lines changed: 6 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,9 @@
11
# Examples
22

3-
## Petstore
3+
| Example | Description |
4+
|---|---|
5+
| [Petstore](petstore.md) | Full walkthrough using the standard Petstore sample API |
6+
| [Authentication](authentication.md) | Configuring bearer token, API key, and basic authentication |
7+
| [Debugging](debugging.md) | Inspecting requests without sending them using mock mode |
48

5-
This example uses the [Petstore](https://petstore3.swagger.io/api/v3/openapi.json) spec — a standard OpenAPI sample API. It has three operations under a `pets` tag and a public demo server, making it a good starting point.
6-
7-
### 1. Generate the client
8-
9-
Download the spec and run the generator:
10-
11-
```bash
12-
curl -o petstore.yaml https://petstore3.swagger.io/api/v3/openapi.json
13-
openapidyalog petstore.yaml ./petstore-client
14-
```
15-
16-
The generated output will be in `./petstore-client/APLSource/`.
17-
18-
### 2. Load into Dyalog
19-
20-
Start Dyalog APL and load the generated code with LINK:
21-
22-
```apl
23-
]LINK.Create # ./petstore-client/APLSource
24-
```
25-
26-
### 3. Create a client instance
27-
28-
The Petstore spec declares a base URL; we pass it explicitly here:
29-
30-
```apl
31-
config ← (baseUrl: 'https://petstore3.swagger.io/api/v3')
32-
client ← ⎕NEW Client config
33-
```
34-
35-
### 4. List pets
36-
37-
```apl
38-
response ← client.pets.ListPets ()
39-
response.HttpStatus
40-
200
41-
response.Data
42-
#.[JSON object]
43-
```
44-
45-
The response body is parsed automatically from JSON into a namespace. Individual pets are accessible as elements of the returned array.
46-
47-
### 5. Fetch a pet by ID
48-
49-
```apl
50-
response ← client.pets.ShowPetById (petId: 1)
51-
response.HttpStatus
52-
200
53-
response.Data.name
54-
doggie
55-
```
56-
57-
### 6. Check for errors
58-
59-
```apl
60-
response ← client.pets.ShowPetById (petId: 9999)
61-
response.HttpStatus
62-
404
63-
response.IsOK
64-
0
65-
```
66-
67-
See [Error Handling](../generated-client/error-handling.md) for how to handle this in production code.
68-
69-
---
70-
71-
## Bearer token authentication
72-
73-
This example shows how to configure a client for an API that requires a bearer token.
74-
75-
```apl
76-
config ← (
77-
baseUrl: 'https://api.example.com'
78-
security: (bearerToken: 'env:[API_TOKEN]')
79-
)
80-
client ← ⎕NEW Client config
81-
```
82-
83-
Setting the `bearerToken` field to `env:[API_TOKEN]` causes the client to read the value of the `API_TOKEN` environment variable at request time, so the token is never hardcoded. With the token set in the environment:
84-
85-
```bash
86-
export API_TOKEN=my-secret-token
87-
```
88-
89-
Requests will include the header `Authorization: Bearer my-secret-token` automatically.
9+
More examples are planned.

‎docs/examples/petstore.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Petstore
2+
3+
This example uses the [Petstore](https://petstore3.swagger.io/api/v3/openapi.json) spec — a standard OpenAPI sample API. It has three operations under a `pets` tag and a public demo server, making it a good starting point.
4+
5+
### 1. Generate the client
6+
7+
Download the spec and run the generator:
8+
9+
```bash
10+
curl -o petstore.yaml https://petstore3.swagger.io/api/v3/openapi.json
11+
openapidyalog petstore.yaml ./petstore-client
12+
```
13+
14+
The generated output will be in `./petstore-client/APLSource/`.
15+
16+
### 2. Load into Dyalog APL
17+
18+
Start Dyalog APL and load the generated code with LINK:
19+
20+
```apl
21+
]LINK.Create # ./petstore-client/APLSource
22+
```
23+
24+
### 3. Create a client instance
25+
26+
The Petstore spec declares a base URL; we pass it explicitly here:
27+
28+
```apl
29+
config ← (baseUrl: 'https://petstore3.swagger.io/api/v3')
30+
client ← ⎕NEW Client config
31+
```
32+
33+
### 4. List pets
34+
35+
```apl
36+
response ← client.pets.ListPets ()
37+
response.HttpStatus
38+
200
39+
response.Data
40+
#.[JSON object]
41+
```
42+
43+
The response body is parsed automatically from JSON into a namespace. Individual pets are accessible as elements of the returned array.
44+
45+
### 5. Fetch a pet by ID
46+
47+
```apl
48+
response ← client.pets.ShowPetById (petId: 1)
49+
response.HttpStatus
50+
200
51+
response.Data.name
52+
doggie
53+
```
54+
55+
### 6. Check for errors
56+
57+
```apl
58+
response ← client.pets.ShowPetById (petId: 9999)
59+
response.HttpStatus
60+
404
61+
response.IsOK
62+
0
63+
```
64+
65+
See [Error Handling](../generated-client/error-handling.md) for how to handle this in production code.

‎mkdocs.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,11 @@ nav:
3737
- Operation Functions: generated-client/operations.md
3838
- Using the Client: generated-client/using-the-client.md
3939
- Error Handling: generated-client/error-handling.md
40-
- Examples: examples/index.md
40+
- Examples:
41+
- Overview: examples/index.md
42+
- Petstore: examples/petstore.md
43+
- Authentication: examples/authentication.md
44+
- Debugging: examples/debugging.md
4145

4246
markdown_extensions:
4347
- admonition

0 commit comments

Comments
 (0)