magic.lambda.http - Invoking HTTP endpoints from Hyperlambda

The magic.lambda.http project provides HTTP invocation capabilities for Magic and Hyperlambda. More specifically the project contains the following 5 slots.

[http.get] - Returns some resource using the HTTP GET verb towards the specified URL
[http.delete] - Deletes some resource using the HTTP DELETE verb
[http.post] - Posts some resources to some URL using the HTTP POST verb
[http.put] - Puts some resources to some URL using the HTTP PUT verb
[http.patch] - Patches some resources to some URL using the HTTP PATCH verb

The [http.put], [http.post] and [http.patch] slots requires you to provide a [payload] or [filename] argument that will be transferred to the endpoint as is. All 5 endpoints can (optionally) take a [token] arguments, which will be transferred as a Bearer Authorization token to the endpoint in the Authorization header of your request. If you provide a [filename] argument, this is assumed to be a file relatively found within your “/files/” folder somewhere. Below is an example of retrieving the document found at the specified URL by creating an HTTP GET request.

http.get:"https://google.com"

The above will result in something resembling the following.

http.get:int:200
   headers
      Cache-Control:no-store, must-revalidate, no-cache, max-age=0
      Pragma:no-cache
      Date:"Mon, 29 Nov 2021 06:11:01 GMT"
      // ... etc ...
   content:"... content here ..."

The status code of the request is returned as the value of [http.xxx], headers returned by the server can be found in [headers] as a key/value pair, and [content] contains the actual content response object returned by the server.

HTTP headers

If you want to have more control over your HTTP request, you can also explicitly add your own [headers] collection, which will become the HTTP request’s headers, where the header name is the name of the node, and its value is the value of the node. Below is an example.

http.get:"https://google.com"
   headers
      Accept:text/html

If you don’t add an explicit [headers] collection the invocation will assume your request payload and accepted response is JSON. If you want to change this you’ll have to add at least one header to your request, at which point the default headers will not be applied.

POSTing, PUTting, and PATCHing data

The POST, PUT and PATCH slots, requires a [payload] argument, or a [filename] argument, that becomes the body of the request. Below is an example illustrating how to create a POST request, with a Bearer token to access the end resource.

http.post:"https://some-url.com"
   token:qwerty_secret_JWT_token_goes_here
   payload:some mumbo jumbo payload, typically JSON and not text though ...

Notice - If you want to submit a large file to some endpoint, without loading the file into memory first, you should rather use [filename] instead of [payload]. This ensures the file is submitted to your endpoint without loading it into memory first.

http.post:"https://some-url.com"
   filename:/README.md

Automatic conversion

You can also automatically convert the resulting response object to a lambda object if you have a registered conversion function, and you provide a [convert] argument, and set its value to boolean true. Below is an example.

http.get:"https://jsonplaceholder.typicode.com/posts"
   convert:bool:true

The above will result in something resembling the following.

http.get:int:200
   headers
      Date:"Mon, 29 Nov 2021 06:19:29 GMT"
      Transfer-Encoding:chunked
      Connection:keep-alive
      // ... etc ...
   content
      .
         userId:long:1
         id:long:1
         title:sunt aut facere repellat provident occaecati excepturi optio reprehenderit
         body:qwerty1
      .
         userId:long:1
         id:long:2
         title:qui est esse
         body:qwerty2
      // ... etc ...

The project contains automatic conversions for the following types out of the box, but you can easily register your own C# based conversion types for specific “Content-Type” values.

application/json
application/x-json
application/hyperlambda
application/x-hyperlambda
application/www-form-urlencoded
application/x-www-form-urlencoded
multipart/form-data

You can also convert a semantic lambda object to the correct request content in a similar fashion, by instead of providing a value to your [payload] node provide a lambda object such as illustrated below.

.userId:int:1
http.post:"https://jsonplaceholder.typicode.com/posts"
   payload
      id:int:1
      userId:x:@.userId

The above will transform your payload to a JSON object automatically for you, and also unwrap any expressions found in your lambda object before JSON transformation is applied. Automatic transformation will only be applied if you’ve got a transformation function registered. If you want to extend the list of supported content types to automatically transform back and forth to, you can use either Magic.Http.AddRequestHandler or MagicHttp.AddResponseHandler to add support for your own automatic transformation for both the request payload and/or the response content.

Notice - The [payload] node above must have a null value, otherwise the slot will prioritise the value, and not attempt to transform from a semantic lambda object in any ways. Values in your [payload] will be transferred as is, and you can provide byte[] arrays, streams or strings as the value of your [payload] node.

Notice - Both the URL encoded request transformer and the JSON request transformer will automatically evaluate expressions in your semantic [payload] object, but this is not true for the Hyperlambda request transformer, since in Hyperlambda it might make sense to actually pass in expressions to the endpoint. Below is an example of how to semantically pass in a Hyperlambda object to some URL.

http.post:"https://foo.com/hyperlambda-endpoint"
   headers
      Content-Type:application/hyperlambda
   payload
      .foo
         .:Thomas
         .:John
      for-each:x:@.foo
         // ... etc ...

The above will automatically serialize your lambda object as Hyperlambda, since the Content-Type is of a type supported by the automatic conversion functions, and transfer the request as a string to the endpoint, preserving expressions as is without unwrapping them before transmitting your [payload].

Passing in multipart/form-data payloads with your HTTP requests

You can also transfer multipart/form-data with all HTTP slots in Hyperlambda. This internally will use the MIME parser to semantically create a multipart message. Below is example code of how to achieve this.

http.post:"http://localhost:5000/magic/modules/foo/foo"
   headers
      Content-Type:multipart/form-data
   payload
      entity:text/plain
         headers
            Content-Disposition:"form-data; name=\"foo\""
         content:Foo bar
      entity:text/plain
         headers
            Content-Disposition:"form-data; filename=\"README.md\""
         filename:/README.md

If you create an HTTP endpoint in Hyperlambda with the filename of “/modules/foo/foo.post.hl”, resembling the following, you can see how the content is transferred in your log.

.accept:multipart/form-data
request.headers.list
lambda2hyper:x:../*
log.info:x:-

How to use [http.get]

This slot accepts a URL as its value, an optionally http headers as a [headers] argument. In its simplest version it would resemble something such as the following.

http.get:"https://docs.aista.com"

The slot returns the result of the specified HTTP GET invocation, including the HTTP headers returned from the endpoint, and status code, in addition to the response object itself.

How to use [http.put]

This slot accepts a URL as its value, an optionally http headers as a [headers] argument, and a mandatory [payload] argument, being whatever payload you want to transfer to the endpoint. In its simplest version it would resemble something such as the following.

http.put:"https://some_website.com/your-put-endpoint"
   payload:@"{""foo"": ""bar""}"

The slot returns the result of the specified HTTP PUT invocation, including the HTTP headers returned from the endpoint, and status code, in addition to the response object itself. To automatically convert the response object to whatever type of response your URL returns, provide a [convert] argument, and set its value to true, such as follows.

http.put:"https://some_website.com/your-put-endpoint"
   payload:@"{""foo"": ""bar""}"
   convert:true

How to use [http.post]

http.post:"https://some_website.com/your-post-endpoint"
   payload:@"{""foo"": ""bar""}"

The slot returns the result of the specified HTTP POST invocation, including the HTTP headers returned from the endpoint, and status code, in addition to the response object itself. To automatically convert the response object to whatever type of response your URL returns, provide a [convert] argument, and set its value to true, such as follows.

http.post:"https://some_website.com/your-post-endpoint"
   payload:@"{""foo"": ""bar""}"
   convert:true

How to use [http.patch]

http.patch:"https://some_website.com/your-patch-endpoint"
   payload:@"{""foo"": ""bar""}"

The slot returns the result of the specified HTTP PATCH invocation, including the HTTP headers returned from the endpoint, and status code, in addition to the response object itself. To automatically convert the response object to whatever type of response your URL returns, provide a [convert] argument, and set its value to true, such as follows.

http.patch:"https://some_website.com/your-patch-endpoint"
   payload:@"{""foo"": ""bar""}"
   convert:true

How to use [http.delete]

This slot accepts a URL as its value, an optionally http headers as a [headers] argument. In its simplest version it would resemble something such as the following.

http.delete:"https://your_website.com/your-delete-endpoint"

The slot returns the result of the specified HTTP DELETE invocation, including the HTTP headers returned from the endpoint, and status code, in addition to the response object itself.

Project website for magic.lambda.http

The source code for this repository can be found at github.com/polterguy/magic.lambda.http, and you can provide feedback, provide bug reports, etc at the same place.