HTTP Requests

Devlish provides HTTP verbs as native keywords for interacting with web APIs. Each verb compiles to a dedicated opcode and dispatches through the host runtime.

GET Requests

Retrieve data from a URL:

Get the url at "https://api.example.com/projects" as response
projects equals body of response

POST Requests

Submit data to an endpoint:

payload equals record with "Solar Farm" as name and 5000000 as value
Post to "https://api.example.com/projects" with payload as response

PUT Requests

Update an existing resource:

updated_item equals record with "complete" as status
Put to "https://api.example.com/projects/42" with updated_item as response

DELETE Requests

Remove a resource:

Delete the url at "https://api.example.com/projects/42" as response

Response Structure

Every HTTP request returns a record with three fields:

Field	Type	Description
`status`	number	HTTP status code (200, 404, etc.)
`headers`	record	Response headers
`body`	record or string	Parsed JSON if content-type is JSON, otherwise raw text

Get the url at "https://api.example.com/data" as response

If status of response equals 200:
  data equals body of response
  Print data
Otherwise:
  Print "Request failed"

Syntax Reference

Verb	Syntax	Has Body
Get	`Get the url at "<url>" as <var>`	No
Post	`Post to "<url>" with <body> as <var>`	Yes
Put	`Put to "<url>" with <body> as <var>`	Yes
Delete	`Delete the url at "<url>" as <var>`	No

Error Handling

HTTP requests can fail due to network errors or host restrictions. Use Try/Otherwise for recovery:

Try:
  Get the url at "https://api.example.com/status" as response
  If status of response >= 400:
    Fail with "API returned error"
  data equals body of response
Otherwise:
  Print last_error
  data equals record with "unavailable" as status

Building Request Bodies

Construct records with the fields your API expects:

request_body equals record with "enterprise" as tier and 500000 as deal_size and true as active

Post to "https://api.example.com/assess" with request_body as response

If status of response equals 200:
  risk_score equals score of body of response
  Print risk_score

Permissions

Programs that make HTTP requests should declare the permission in their manifest:

Permissions:
  HTTP requests to "api.example.com"

Without a manifest, HTTP requests are unrestricted. With a manifest, undeclared domains are blocked at runtime.