API connections

An API lets your program communicate with another service. Creole keeps addresses, keys, limits, and requests readable.

Keep real API keys outside .crlo files. Read them from environment values or future native secret storage.

Name a connection

Make API ai.
  Address is environment value "AI_ADDRESS".
  Key is environment value "AI_KEY".
  Wait at most 60 seconds.
  Try 3 times.
  Limit is 10 MB.
End.

ai is only the name chosen for this connection. API objects can use any clear name.

The block keeps connection settings together:

• Address is the provider base address
• Key reads the private key from the environment
• Wait at most prevents an endless request
• Try controls retries
• Limit prevents an unexpectedly large response

Get information

Get from "/items" using ai as response.

If response's successful.
  Show response's data in JSON.
Else.
  Show response's status.
  Show response's text.
End.

Always check whether a request succeeded before depending on its data.

Send native data

Make record payload.
  Message is "Hello from Creole".
  Active is true.
End.

Send payload to "/chat" using ai as response.

Creole sends a record or list body as JSON when the API needs it. Your source stays in native Creole form.

Other operations

Get from "/items" using ai as response.
Replace payload at "/items/1" using ai as response.
Change payload at "/items/1" using ai as response.
Delete from "/items/1" using ai as response.

Use the operation required by the API documentation.

Understand a response

A response can include its status, success value, text, headers, and parsed data.

Show response's status.
Show response's text.
Show response's data in JSON.

Valid JSON response data is available as native Creole data.

Safe request habits

• Keep tokens outside source files.
• Use HTTPS addresses.
• Set time and size limits.
• Retry only safe operations.
• Do not show private response data in public logs.
• Test with non-sensitive data first.
• Handle unsuccessful responses clearly.

Learning checklist

• I can name an API connection.
• I can read a key from an environment value.
• I can set time, retry, and size limits.
• I can get and send data.
• I check response's successful.
• I keep private keys out of source code.

Next step

Continue to Streaming to read live Server-Sent Events as they arrive.