Documention for: rest.r
Created by: chrisrg
 on: 11-Nov-2008
Last updated by: chrisrg on: 11-Nov-2008
Format: text/editable
Downloaded on: 30-Apr-2025

REST-Friendly HTTP Protocol

===Introduction

An elementary HTTP protocol allowing more versatility when developing Web Services clients: REST, SOAP or other.

===Usage

It is best loaded to it's own context, no new global words are exposed:

	context load %rest.r

This installs the rest:// protocol:

	rest://rebol.org

Reading a rest:// URL returns an object:

	>> reborg: read rest://rebol.org
	>> ? reborg
	REBORG is an object of value: 
	   status          integer!  200 
	   headers         object!   [Date Server Last-Modified Accept-Ranges Content-E... 
	   content         binary!   #{ 323030300D0A3C21444F43545950452048544D4C2050554... 
	   type            path!     length: 2 
	   length          integer!  0

:status - HTTP Response Status Code

:headers - HTTP Response Headers

:content - Resource content, always binary

:type - Resource content MIME type

:length - Resource content length

Providing a custom block affords some control over the HTTP request:

	read/custom rest://rebol.org [
		action: 'get
	]

	read/custom rest://myblog/posts/new [
		action: 'post
		content: {This is text}
		type: 'text/plain
	]

	read/custom rest://myblog/images/new [
		action: 'put
		content: #{... some image binary ...}
		type: 'image/png
		headers: [auth: #MYPASS]
		version: 1.1
	]

:action - HTTP Verb

:content - Request content, string or binary

:type - Request content MIME type

:headers - Request HTTP headers, as required

:version - HTTP version (default 1.1)

===Future

*Finer tuned request dialect options, following common REST patterns

*Better developed response object, including:

**Detection and conversion of response text types

**Status words in addition to codes (e.g. 'ok 'not-found 'server-error)