Difference between revisions of "HTTP (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Updated to API overview v2)
m (fixed formatting)
 
(14 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{NeedsWork|"A summary is required." need to be replaced. ''[[User:AfterLifeLochie|AfterLifeLochie]] 02:13, 1 December 2012 (MSK)''}}
 
 
 
:{|class="wikitable"
 
:{|class="wikitable"
| '''The HTTP API must be enabled in mod_ComputerCraft.cfg before being used. To enable it open .minecraft/config/mod_ComputerCraft.cfg and change enableAPI_http=0 to enableAPI_http=1.'''
+
| '''The HTTP API must be enabled in ComputerCraft.cfg before being used. To enable it see [http://www.computercraft.info/forums2/index.php?/topic/17533-how-to-enable-the-http-api/ this tutorial].'''
 
|}
 
|}
  
 
The HTTP API allows interfacing with websites and downloading from them.
 
The HTTP API allows interfacing with websites and downloading from them.
  
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
+
{{API table|HTTP|image=Grid disk.png|2=
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
+
 
[[File:Grid_disk.png|24px]]&nbsp;&nbsp;
+
{{API table/row
HTTP (API)
+
|[[http.request]]({{type|string}} url [, {{type|string}} postData [, {{type|table}} headers]])
</td></tr>
+
|{{type|nil}}
 +
|Sends a HTTP request to a website, asynchronously.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[http.get]]({{type|string}} url [, {{type|table}} headers])
 +
|{{type|table}} handle
 +
|Sends a HTTP GET request to a website, synchronously.
 +
|}}
 +
 
 +
{{API table/row
 +
|[[http.post]]({{type|string}} url, {{type|string}} postData [, {{type|table}} headers])
 +
|{{type|table}} handle
 +
|Sends a HTTP POST request to a website, synchronously.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[http.checkURL]]({{type|string}} url)
 +
|{{type|boolean}} success [<nowiki />, {{type|string}} error]
 +
|Checks if a URL is valid and is included in the HTTP whitelist.
 +
|}}
  
<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>
+
}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.request]]( url, *postData )</td>
+
[[http.request]] is used to send a HTTP request that completes asynchronously and generates an event (one of [[Http success (event)|http_success]] or [[Http failure (event)|http_failure]]). [[http.get]] and [[http.post]] execute [[http.request]] and block until the operation completes.
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">A summary is required.</td></tr>
+
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.get]]( url )</td>
+
== Handles ==
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">A summary is required.</td></tr>
+
All three operations make use of ''handles'', tables that contain functions to read data returned from the HTTP server. These handles act the same as the I/O handles returned by [[fs.open]] in read-only text mode, implementing the [[fs.open#Closing_a_file_handle|close]], [[fs.open#Files_opened_in_text_read_mode|readLine]], and [[fs.open#Files_opened_in_text_read_mode|readAll]] methods. These handles also implement the following function:
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.post]]( url, postData )</td>
+
{{Function
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">A summary is required.</td></tr>
+
|name=<var>h</var>.getResponseCode
</table>
+
|returns={{type|number}} HTTP response code
 +
|api=HTTP
 +
|desc=Returns the numerical [https://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP response code] sent by the server
 +
}}
  
A period of time after a http.request() call is made, a "http_success" or "http_failure" event will be raised to os.pullEvent(). Arguments are the URL and a file handle if successful. http.get() blocks until this event is fired.
+
== Headers ==
 +
As of '''ComputerCraft 1.63''', you can optionally set custom headers. This also means that you can override default headers such as the User-Agent.
 +
{{Example
 +
|desc=Sends a request to http://example.com/ with the custom headers.
 +
|code=local headers = {
 +
  [ "User-Agent" ] = "A custom user-agent!", ''-- Overrides the default User-Agent.''
 +
  [ "Hi" ] = "Hello" ''-- A non-standard custom header field.''
 +
}
 +
 +
[[http.get]]( "http:<nowiki/>//example.com/", headers )
 +
}}
  
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 20:35, 1 August 2015

The HTTP API must be enabled in ComputerCraft.cfg before being used. To enable it see this tutorial.

The HTTP API allows interfacing with websites and downloading from them.

Grid disk.png  HTTP (API)
Function Return values Description
http.request(string url [, string postData [, table headers]]) nil Sends a HTTP request to a website, asynchronously.
http.get(string url [, table headers]) table handle Sends a HTTP GET request to a website, synchronously.
http.post(string url, string postData [, table headers]) table handle Sends a HTTP POST request to a website, synchronously.
http.checkURL(string url) boolean success [, string error] Checks if a URL is valid and is included in the HTTP whitelist.

http.request is used to send a HTTP request that completes asynchronously and generates an event (one of http_success or http_failure). http.get and http.post execute http.request and block until the operation completes.

Handles

All three operations make use of handles, tables that contain functions to read data returned from the HTTP server. These handles act the same as the I/O handles returned by fs.open in read-only text mode, implementing the close, readLine, and readAll methods. These handles also implement the following function:


Grid Redstone.png  Function h.getResponseCode
Returns the numerical HTTP response code sent by the server
Syntax h.getResponseCode()
Returns number HTTP response code
Part of ComputerCraft
API HTTP


Headers

As of ComputerCraft 1.63, you can optionally set custom headers. This also means that you can override default headers such as the User-Agent.

Grid paper.png  Example
Sends a request to http://example.com/ with the custom headers.
Code
local headers = {
  [ "User-Agent" ] = "A custom user-agent!", -- Overrides the default User-Agent.
  [ "Hi" ] = "Hello" -- A non-standard custom header field.
}

http.get( "http://example.com/", headers )