HARP - Hypermedia Abstract Resource Protocol

harp-request.md

Requirements:

1. One line query through uri.
2. Filtering
3. Sorting
4. Limitation
5. Partial fetching
6. Fetching linked resources
7. Normalized response
8. Bulk requests
9. Metadata discovery

URI special symbols (encoded by encodeURIComponent but not encodeURI): =, @, #, $, &, +, ;, :, ,, /, ?.

Common query string format: pairs separated by &, key and value separated by =. Common path format: chunks sparated by /. : can't be used in first chunk of path. Repeated ? and # may be escaped by some libs.

So mostly safe symbols: =, @, $, &, +, ;, ,, /.

Symbols that can be used in the path in any place, escaped by encodURIComponent, but not escaped by ChromeDev Tools: /, @, $, &, +, =, [, ], ;, ,.

Examples:

• / - metadata of all types
• /user=jin,john[name][age] - name and age of users by primary key
• /user[sex=male,female][age=&18,20,40&50,100&][role@admin] - sex, age and role of users by filter: male or female but not trans, and not admin, with age <=18, age = 20, 40 <= age <= 50, age >= 100
• /user[+birthday=2000-01-01&][-created][&10] - 10 users with birthday from 2000-01-01 sorted by birthday asc then created desc
• /user[name][friend[name][-age=18&][&10]] - users with names and 10 older friends with names and ages that have age > 18
• /user=jin[friend[name]],article=hello[liker[name]] - all "jin" friend names and "hello" liker names, without users data dublication

Syntax:

1. Field name: user, article etc.
2. Order field predicate: + - asc, - - desc.
3. Fetch modifier: [field] - additinal fetch of this field, [10&20] - slice part of list
4. Predicates for filtering: = - positive, @ - negative
5. Lists: 1,2,3
6. Range: 1&5 - between, 1& - greated then or equal, &5 - lower then or equal, 3 - only this value

harp-response.json

{
	"user": {
		"user=jin": {
			"name": "Jin",
			"karma": 100500,
			"birthday": "1984-08-04",
			"creation": [
				"article=foo",
				"article=bar"
			]
		}
	},
	"bot": {
		"bot=google": {
			"name": "GoogleBot",
			"creation": [
				"article=bar"
			]
		}
	},
	"article": {
		"article=foo": {
			"name": "Fooooo",
			"author": [
				"user=jin"
			]
		},
		"article=bar": {
			"name": "Barrrr",
			"author": [
				"user=jin" ,
				"bot=google"
			]
		}
	}
}

harp-response.tree

user user=jin
	name \Jin
	karma 100500
	birthday \1984-08-04
	creation
		article=foo
		article=bar
bot bot=google
	name \GoogleBot
	creation article=bar
article
	article=foo
		name \Fooooo
		author user=jin
	article=bar
		name \Barrrr
		author
			user=jin
			bot=google