<library name="Http">
	<description>Library for sending HTTP requests.</description>
	<namespace name="Http">
		
		<enum name="Method">
			<description>
				Various common HTTP Methods. Any function that accepts this enum is also capable of accepting a 
				string for custom or obscure HTTP methods.
			</description>
			<value name="GET"/>
			<value name="POST"/>
			<value name="PUT"/>
			<value name="DELETE"/>
		</enum>
		
		<enum name="StatusCode">
			<description>
				Enum for standard status codes. 
				Note that a status code received by a server can be arbitrary and may not necessarily be represented in this enum.
				Each enum value's integer value is identical to the code it represents e.g. the enum value 
				StatusCode.NOT_FOUND resolves to the integer 404.
			</description>
			
			<value name="CONTINUE" description="100"/>
			<value name="SWITCHING_PROTOCOLS" description="101"/>
			<value name="PROCESSING" description="102"/>
			<value name="CHECKPOINT" description="103"/>

			<value name="OK" description="200"/>
			<value name="CREATED" description="201"/>
			<value name="ACCEPTED" description="202"/>
			<value name="NON_AUTHORITATIVE_INFORMATION" description="203"/>
			<value name="NO_CONTENT" description="204"/>
			<value name="RESET_CONTENT" description="205"/>
			<value name="PARTIAL_CONTENT" description="206"/>
			<value name="MULTI_STATUS" description="207"/>
			<value name="ALREADY_REPORTED" description="208"/>
			<value name="IM_USED" description="226"/>

			<value name="MULTIPLE_CHOICES" description="300"/>
			<value name="MOVED_PERMANENTLY" description="301"/>
			<value name="MOVED_TEMPORARILY" description="302"/>
			<value name="SEE_OTHER" description="303"/>
			<value name="NOT_MODIFIED" description="304"/>
			<value name="USE_PROXY" description="305"/>
			<value name="SWITCH_PROXY" description="306"/>
			<value name="TEMPORARY_REDIRECT" description="307"/>
			<value name="PERMANENT_REDIRECT" description="308"/>

			<value name="BAD_REQUEST" description="400"/>
			<value name="UNAUTHORIZED" description="401"/>
			<value name="PAYMENT_REQUIRED" description="402"/>
			<value name="FORBIDDEN" description="403"/>
			<value name="NOT_FOUND" description="404"/>
			<value name="METHOD_NOT_ALLOWED" description="405"/>
			<value name="NOT_ACCEPTABLE" description="406"/>
			<value name="PROXY_AUTHENTICATION_REQUIRED" description="407"/>
			<value name="REQUEST_TIMEOUT" description="408"/>
			<value name="CONFLICT" description="409"/>
			<value name="GONE" description="410"/>
			<value name="LENGTH_REQUIRED" description="411"/>
			<value name="PRECONDITION_FAILED" description="412"/>
			<value name="PAYLOAD_TOO_LARGE" description="413"/>
			<value name="URI_TOO_LONG" description="414"/>
			<value name="UNSUPPORTED_MEDIA_TYPE" description="415"/>
			<value name="RANGE_NOT_SATISFIABLE" description="416"/>
			<value name="EXPECTATION_FAILED" description="417"/>
			<value name="IM_A_TEAPOT" description="418"/>
			<value name="ENHANCE_YOUR_CALM" description="420"/>
			<value name="MISDIRECTED_REQUEST" description="421"/>
			<value name="UNPROCESSABLE_ENTITY" description="422"/>
			<value name="LOCKED" description="423"/>
			<value name="FAILED_DEPENDENCY" description="424"/>
			<value name="UPGRADE_REQUIRED" description="426"/>
			<value name="PRECONDITION_REQUIRED" description="428"/>
			<value name="TOO_MANY_REQUESTS" description="429"/>
			<value name="REQUEST_HEADER_FIELDS_TOO_LARGE" description="431"/>
			<value name="LOGIN_TIMEOUT" description="440"/>
			<value name="RETRY_WITH" description="449"/>
			<value name="BLOCKED_BY_PARENTAL_CONTROLS" description="450"/>
			<value name="UNAVAILABLE_FOR_LEGAL_REASONS" description="451"/>

			<value name="INTERNAL_SERVER_ERROR" description="500"/>
			<value name="NOT_IMPLEMENTED" description="501"/>
			<value name="BAD_GATEWAY" description="502"/>
			<value name="SERVICE_UNAVAILABLE" description="503"/>
			<value name="GATEWAY_TIMEOUT" description="504"/>
			<value name="HTTP_VERSION_NOT_SUPPORTED" description="505"/>
			<value name="VARIANT_ALSO_NEGOTIATES" description="506"/>
			<value name="INSUFFICIENT_STORAGE" description="507"/>
			<value name="LOOP_DETECTED" description="508"/>
			<value name="BANDWIDTH_LIMIT_EXCEEDED" description="509"/>
			<value name="NOT_EXTENDED" description="510"/>
			<value name="NETWORK_AUTHENTICATION_REQIURED" description="511"/>
		</enum>

		<class name="HttpResponse">

			<description>
				Contains the contents of an HTTP Response from a server.
			</description>

			<function name="getHeaderNames">
				<returns type="list-of-string" description="A list of the header names in the HTTP response"/>
				<description>
					Returns the list of the names of the headers in an HTTP response. 
					This can be used in conjunction with .getHeader(name) or .getHeaders(name).
				</description>
			</function>

			<function name="getHeader">
				<returns type="string" description="The first header with that name or null."/>
				<description>
					Gets the string value of the given header name.
					Lookup is case-insensitive.
					If no header is found, null is returned.
					If there are multiple headers, only one is returned.
					To get all headers with that name, use .getHeaders(name).
				</description>
			</function>

			<function name="getHeaders">
				<returns type="list-of-string" description="The headers with that name."/>
				<description>
					Gets all the string values for the header with the given name.
					Lookup is case-insensitive and if multiple headers exist with different casing, all are still returned.
					If no header is found, the list will be empty.
					To get a default header as a string (as opposed to a list) use .getHeader(name).
				</description>
			</function>

			<function name="getContent">
				<returns type="string|list-of-int" description="The content of the body of the response."/>
				<description>
					Returns the content of the body of the response. 
					If the mode of the originating request was TEXT, then the return value will be a string.
					If the mode of the originating request was BINARY, then the return value will be a list of integers
					representing bytes.
					If there is no body, an empty string or empty list will be returned.
				</description>
			</function>

			<function name="getStatusCode">
				<returns type="Http.StatusCode|int" description="The status code of the response."/>
				<description>
					Returns the status code of the response. 
					Value will be 0 if the request has not completed.
					The return value will always be an integer, but will commonly be a value in the Http.StatusCode enum.
				</description>
			</function>

			<function name="getStatusMessage">
				<returns type="string" description="The status message of the response."/>
				<description>
					Returns the status message of the response.
					This is the brief text description that is generally associated with the status code. 
					For example, the "NOT FOUND" in "404 NOT FOUND".
					This value can be arbitrary as it is provided by the server and may not necessarily adhere to well-known values.
				</description>
			</function>
		</class>

		<enum name="RequestMode">
			<description>Enum representing what format the response should be parsed as.</description>
			<value name="TEXT" description="Response should be treated as a text string."/>
			<value name="BINARY" description="Response should be treated as a list of byres."/>
		</enum>

		<class name="HttpRequest">
			<description>
				Builds, sends, and manages an outgoing HTTP request.
			</description>

			<function name="(constructor)">
				<arg name="url" type="string" description="URL to send the request to."/>
				<description>
					Instantiates a new HTTP request, but does not send the request until you invoke
					.send() or .sendAsync().
				</description>
			</function>

			<function name="setMethod">
				<arg name="method" type="Http.Method|string" description="Method to use for the outgoing HTTP request."/>
				<returns type="Http.HttpRequest" description="Returns a reference to itself to allow for builder syntax."/>
				<description>
					Sets the HTTP method for the outgoing request.
					If this is one of the common 4 values (GET, POST, PUT, or DELETE), the Http.Method enum can be used.
					If it is a custom or obscure method, an arbitrary string can be passed in instead.
				</description>
			</function>

			<function name="setHeader">
				<arg name="name" type="string" description="Name of the header to set."/>
				<arg name="value" type="string" description="Value of the header to set."/>
				<returns type="Http.HttpRequest" description="Returns a reference to itself to allow for builder syntax."/>
				<description>
					Sets a header with the given name. 
					If invoked multiple times with the same header name, multiple headers will be sent 
					(rather than) overwriting the previous value.
				</description>
			</function>

			<function name="setContent">
				<arg name="value" type="string" description="The content of the outgoing request."/>
				<arg name="contentType" type="string" optional="true" default="null" description="The Content-Type header of the outgoing request"/>
				<returns type="Http.HttpRequest" description="Returns a reference to itself to allow for builder syntax."/>
				<description>
					Sets the content of the outgoing request as a UTF-8 encoded text string.
					Optionally, you can set the Content-Type at the same time, which is redundant with calling .setHeader('Content-Type', value), but more convenient.
					If you want to send binary content in the request body, see setContentBytes().
				</description>
			</function>

			<function name="setContentBytes">
				<arg name="value" type="list-of-int" description="The content of the outgoing request."/>
				<arg name="contentType" type="string" optional="true" default="null" description="The Content-Type header of the outgoing request"/>
				<returns type="Http.HttpRequest" description="Returns a reference to itself to allow for builder syntax."/>
				<description>
					Sets the content of the outgoing request as a list of bytes. 
					All Values will be modded by 256 before being sent.
					Optionally, you can set the Content-Type at the same time, which is redundant with calling .setHeader('Content-Type', value), but more convenient.
					If you want to send text content in the request body, see setContentString().
				</description>
			</function>

			<function name="setMode">
				<arg name="mode" type="Http.RequestMode" description="Expected format of the response."/>
				<returns type="Http.HttpRequest" description="Returns a reference to itself to allow for builder syntax."/>
				<description>
					Indicates to the request whether the body of the response should be treated as text or raw bytes.
				</description>
			</function>

			<function name="send">
				<returns type="Http.HttpResponse" description="Response of the request."/>
				<description>
					Sends the HTTP request and waits for a response.
					This function will block execution of your program. 
					To make a request without blocking, see .sendAsync().
				</description>
			</function>

			<function name="sendAsync">
				<arg name="callback" type="function" description="A function that gets invoked when the HTTP request has completed. This function requires one input that will be an HttpResponse object."/>
				<description>
					Sends the HTTP request and returns immediately while the request runs in the background.
					To check the status of the request, use .isDone() and .getResponse().
					If blocking execution of code is okay, use .send().
				</description>
			</function>

			<function name="isDone">
				<returns type="boolean" description="True if the request has completed (in either an error or success)."/>
				<description>
					Checks to see if the request has completed if sent with .sendAsync().
				</description>
			</function>

			<function name="getResponse">
				<returns type="Http.HttpResponse" description="Response of the HTTP request."/>
				<description>
					Gets the HTTP response.
					Code must check the value of .isDone() before accessing this value.
					Throws an Core.InvalidOperationException if the value of .isDone() is false.
					Furthermore, an exception will also be thrown if .isDone() was never called on the request,
					even if the request is complete.
				</description>
			</function>
		</class>
		
		<function name="urlEncode">
			<arg name="value" type="string" description="A string to percent-encode."/>
			<returns type="string" description="The percent-encoded string."/>
			<description>
				Encodes a string using the percent-encoding system to make it URL safe.
			</description>
		</function>
		
		<function name="urlDecode">
			<arg name="value" type="string" description="A string that is percent-encoded."/>
			<returns type="string" description="The original string value"/>
			<description>
				Decodes a string that has been percent encoded. 
				If the string is not a valid percent encoding format, then an InvalidArgumentException is thrown.
				If the string is in the correct format but the byte values are not valid UTF8, a TextEncoder.TextEncodingException is thrown.
			</description>
		</function>
	</namespace>
</library>