Skip to content

Instantly share code, notes, and snippets.

@nin-jin nin-jin/harp-request.md
Last active Jun 22, 2019

Embed
What would you like to do?
HARP - Hypermedia Abstract Resource Protocol

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[name][age] - name and age of user by primary key
  • /user[sex=male,female][age=&18,18,40&50,100&][role!=admin] - sex and age of users by filter: male or female but not trans, and not admin, with age <18, age = 18, 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 id desc
  • /user[name][friend[name][age=18&][&10]] - users with names and 10 friends with names and ages that have age > 18
  • /user=jin[friend[name]],article=hello[liker[name]] - load 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, &5 - lower then, 3 - only this value
{
"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"
]
}
}
}
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.