|
@@ -0,0 +1,152 @@
|
|
|
+# Uri
|
|
|
+
|
|
|
+## Synopsis
|
|
|
+
|
|
|
+Interacts with HTTP and HTTPS web services.
|
|
|
+
|
|
|
+## Options
|
|
|
+
|
|
|
+| parameter | required | default | choices | comment |
|
|
|
+|----------------|----------|---------|----------------------------------------------|----------------------------------------------------------------------------|
|
|
|
+| url | YES | | | HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path |
|
|
|
+| headers | NO | | E.g: Content-Type: 'application/json' | Add custom HTTP headers to a request in the format of a YAML hash |
|
|
|
+| data | NO | | E.g: "{\"title\": \"foo\"}" | JSON data to send to the server. You must escape quotes in the YAML file. |
|
|
|
+| data_from_file | NO | | E.g: /path/to/my/file.json | JSON data loaded from a file. |
|
|
|
+| method | NO | GET | GET, POST, DELETE, PUT, HEAD, PATCH, OPTIONS | The HTTP method of the request or response. It MUST be uppercase. |
|
|
|
+| user | NO | | | username for the basic authentication. |
|
|
|
+| password | NO | | | passwordfor the basic authentication. |
|
|
|
+| timeout | NO | | | The socket level timeout in seconds. Must be an integer without quotes |
|
|
|
+
|
|
|
+
|
|
|
+## Return Values
|
|
|
+
|
|
|
+| Name | Description | Type | sample |
|
|
|
+|-----------------|----------------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------|
|
|
|
+| status_code | Numeric, HTTP status code that signifies success of the request. | int | 200 |
|
|
|
+| content | The body content of the server answer. May be JSON serialized and usable in a template | string | {"title": "foo", "body": "bar", "userId": 1} |
|
|
|
+| response_header | Response header from the server. | dict | {'Date': 'Sat, 19 Nov 2016 11:17:56 GMT', 'Content-Length': '192', 'Content-Type': 'text/html'} |
|
|
|
+
|
|
|
+## Synapses example
|
|
|
+
|
|
|
+Simple call to a server. The default method is GET
|
|
|
+```
|
|
|
+ - name: "test-get-url"
|
|
|
+ signals:
|
|
|
+ - order: "test-get-url"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/get/1"
|
|
|
+```
|
|
|
+
|
|
|
+A simple call with authentication
|
|
|
+```
|
|
|
+- name: "test-get-url-with-auth"
|
|
|
+ signals:
|
|
|
+ - order: "test-get-url-with-auth"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/get/1"
|
|
|
+ user: "admin"
|
|
|
+ password: "secret"
|
|
|
+```
|
|
|
+
|
|
|
+A simple post with data inside the url
|
|
|
+```
|
|
|
+- name: "test-get-url-with-auth"
|
|
|
+ signals:
|
|
|
+ - order: "test-post-url-with-data"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/login?email=user@host.domain&password=foobar123"
|
|
|
+ method: POST
|
|
|
+```
|
|
|
+
|
|
|
+A post with json data. Note that we need to escape quotes from the payload.
|
|
|
+```
|
|
|
+- name: "test-post-url"
|
|
|
+ signals:
|
|
|
+ - order: "test-post-url"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/posts"
|
|
|
+ method: POST
|
|
|
+ headers:
|
|
|
+ Content-Type: 'application/json'
|
|
|
+ data: "{\"id\": 1,\"title\": \"foo\", \"body\": \"bar\", \"userId\": 1}"
|
|
|
+```
|
|
|
+
|
|
|
+A post with json data imported from a file and a custom header.
|
|
|
+```
|
|
|
+- name: "test-post-url"
|
|
|
+ signals:
|
|
|
+ - order: "test-post-url"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/posts"
|
|
|
+ method: POST
|
|
|
+ headers:
|
|
|
+ Content-Type: 'application/json'
|
|
|
+ user-agent: 'my-app/0.0.1'
|
|
|
+ data_from_file: "/path/to/my/payload.json"
|
|
|
+```
|
|
|
+
|
|
|
+And the `payload.json` would be (note that we don't need to escape any character):
|
|
|
+```
|
|
|
+{"title": "foo", "body": "bar", "userId": 1}
|
|
|
+```
|
|
|
+
|
|
|
+A simple call to a deletion. Here we also ask Kalliope to tell use if request was a success through a template, depending on the returned status code.
|
|
|
+```
|
|
|
+ - name: "test-delete-url"
|
|
|
+ signals:
|
|
|
+ - order: "test-delete-url"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/posts/1"
|
|
|
+ method: DELETE
|
|
|
+ say_template:
|
|
|
+ - "{% if status_code==201 %}delete complete{% else %}fail to delete{% endif %}"
|
|
|
+```
|
|
|
+
|
|
|
+Call to an URL to get a resource and make kalliope speaking out loud a value of returned content.
|
|
|
+Here, we ask the server to return us the user with ID number 42. We know that the server will return a dict like the following
|
|
|
+```
|
|
|
+{
|
|
|
+ "id": 1,
|
|
|
+ "name": "Leanne Graham",
|
|
|
+ "username": "Bret",
|
|
|
+ "email": "Sincere@april.biz",
|
|
|
+ "phone": "1-770-736-8031 x56442",
|
|
|
+ "website": "hildegard.org",
|
|
|
+ "company": {
|
|
|
+ "name": "Romaguera-Crona",
|
|
|
+ "catchPhrase": "Multi-layered client-server neural-net",
|
|
|
+ "bs": "harness real-time e-markets"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Here is the synapse we would use to make Kalliope speak out loud the name of the user and the name of his company
|
|
|
+```
|
|
|
+ - name: "test-get-url-with-template"
|
|
|
+ signals:
|
|
|
+ - order: "test-get-url-with-template"
|
|
|
+ neurons:
|
|
|
+ - uri:
|
|
|
+ url: "http://host.domain/users/1"
|
|
|
+ say_template:
|
|
|
+ - "The user name is {{ content.name }}, the company name is {{ content.company.name }}"
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+## Templates example
|
|
|
+
|
|
|
+The following the template will make kalliope read the content of the received json variable "title" from the remote server
|
|
|
+```
|
|
|
+The title is {{ content.title }}
|
|
|
+```
|
|
|
+
|
|
|
+The following template will make Kalliope say if the request has been made with success or not depending on the returned status code
|
|
|
+```
|
|
|
+{% if status_code==200 %}request complete{% else %}request failled{% endif %}
|
|
|
+```
|