Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Comparing changes

Choose two branches to see what's changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
base fork: hyperrest/hyperrest.github.io
base: 436aa79f32
...
head fork: hyperrest/hyperrest.github.io
compare: efa7c75a65
Checking mergeability… Don't worry, you can still create the pull request.
  • 3 commits
  • 8 files changed
  • 0 commit comments
  • 1 contributor
View
2  _config.yml
@@ -146,7 +146,7 @@ text:
download_zip: Download ZIP File
download_tarball: Download TAR Ball
fork_me_on_github: Fork me on <strong>GitHub</strong>
- maintained_by: maintained by
+ maintained_by: authored by
toc: Table of Contents
related: Related
comments: Comments
View
6 _includes/strap-jekyll/default/content-comments.html
@@ -1,4 +1,4 @@
-<div id="post-comments">
+<div id="page-comments">
{% if site.comments.twitter and site.comments.twitter.enabled == true and page_author.twitter %}
<a href="https://twitter.com/intent/tweet?screen_name={{ page_author.twitter }}&amp;text={{ site.comments.twitter.text }}&amp;url={{ site_pages_url | escape }}{{ page.url | escape }}">{{ text.leave_a_comment_on_twitter_to }} @{{ page_author.twitter }}</a>
<br><br>
@@ -6,8 +6,8 @@
{% if page_comments_github_enabled %}
<!-- http://ivanzuzak.info/2011/02/18/github-hosted-comments-for-github-hosted-blogs.html -->
- <a id="post-comments-url" href="https://github.com/{{ site.comments.github.author }}/{{ site.comments.github.repo }}/issues/{{ page_comments_github_id }}">{{ text.leave_a_comment_on_github }}</a>
- <div id="post-comments-placeholder"></div>
+ <a id="page-comments-url" href="https://github.com/{{ site.comments.github.author }}/{{ site.comments.github.repo }}/issues/{{ page_comments_github_id }}">{{ text.leave_a_comment_on_github }}</a>
+ <div id="page-comments-placeholder"></div>
<br><br>
{% endif %}
View
21 _includes/strap-jekyll/default/header.html
@@ -9,15 +9,6 @@
<meta name="description" content="{% if page.description %}{{ page.description }} | {% endif %}{{ description }}">
<meta name="author" content="{{ page_author.display_name }}">
- <!-- Le styles -->
- <link href="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">
- <link href="//netdna.bootstrapcdn.com/font-awesome/3.0.2/css/font-awesome.css" rel="stylesheet">
- <link href="{{ site.base_url }}/assets/strap-jekyll/css/zocial.css" rel="stylesheet">
-
- <link href="{{ site.base_url }}/assets/strap-jekyll/css/strap-jekyll-default.css" rel="stylesheet">
- <link href="{{ site.base_url }}/assets/strap-jekyll/css/rainbow.css" rel="stylesheet">
- <link href="{{ site.base_url }}/assets/strap-jekyll-default-custom.css" rel="stylesheet">
-
<!-- Le fav and touch icons -->
<link rel="shortcut icon" href="{{ site.base_url }}/assets/strap-jekyll/ico/favicon.ico">
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="{{ site.base_url }}/assets/strap-jekyll/ico/apple-touch-icon-144-precomposed.png">
@@ -25,13 +16,23 @@
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="{{ site.base_url }}/assets/strap-jekyll/ico/apple-touch-icon-72-precomposed.png">
<link rel="apple-touch-icon-precomposed" href="{{ site.base_url }}/assets/strap-jekyll/ico/apple-touch-icon-57-precomposed.png">
- <link type="application/atom+xml" rel="alternate" href="{{ site.base_url }}/atom.xml"/>
+ <!-- Le feed -->
+ <link rel="alternate" type="application/atom+xml" href="{{ site.base_url }}/atom.xml">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.6.2/html5shiv.js"></script>
<![endif]-->
+ <!-- Le styles -->
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css">
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/font-awesome/3.0.2/css/font-awesome.css">
+ <link rel="stylesheet" href="{{ site.base_url }}/assets/strap-jekyll/css/zocial.css">
+
+ <link rel="stylesheet" href="{{ site.base_url }}/assets/strap-jekyll/css/strap-jekyll-default.css">
+ <link rel="stylesheet" href="{{ site.base_url }}/assets/strap-jekyll/css/rainbow.css">
+ <link rel="stylesheet" href="{{ site.base_url }}/assets/strap-jekyll-default-custom.css">
+
{% include strap-jekyll-default-head-custom.html %}
</head>
View
12 _includes/strap-jekyll/default/layouts/post.html
@@ -5,15 +5,15 @@
<h1>
{{ page.title }}
{% if page.date %}
- <small class="post-date">{{ page.date | date_to_string }}</small>
+ <small class="page-date">{{ page.date | date_to_string }}</small>
{% endif %}
</h1>
</div>
- <div class="post-meta">
+ <div class="page-meta">
{% capture category_size %}{{ page.categories | size }}{% endcapture %}
{% if category_size != '0' %}
- <div class="post-categories">
+ <div class="page-categories">
<span>{{ text.categories }}</span>
{% for category in page.categories %}
<div class="btn-group">
@@ -41,7 +41,7 @@
{% endif %}
{% capture tag_size %}{{ page.tags | size }}{% endcapture %}
{% if tag_size != '0' %}
- <div class="post-tags">
+ <div class="page-tags">
<span>{{ text.tags }}</span>
{% for tag in page.tags %}
<div class="btn-group">
@@ -69,7 +69,9 @@
{% endif %}
</div>
- {{ content }}
+ <div class="page-content">
+ {{ content }}
+ </div>
{% if page_comments_enabled == true %}
<h2 id="comments">{{ text.comments }}</h2>
View
71 _posts/2013-03-30-rest-api-concepts.md
@@ -0,0 +1,71 @@
+---
+layout: strap-jekyll-default-post
+title: REST API concepts
+categories: envision spec
+tags: terminology
+published: true
+---
+
+Every now and then I bump into these terms, and [it's not easy to grasp the definitions in a blink of an eye](https://groups.google.com/forum/#!topic/api-craft/ahxTncZZn2I). It's not easy because, while REST models real life concepts in a simple manner, we are not accustomed to so much semantics in daily programming. Everything is mostly data, text, a class, an instance, an object, etc. This post is mainly a note-to-self, but hopefully it has a good-enough analogy that you can use as well.
+
+> Some things might be off, and there <s>might</s> surely are better analogies, so I'd be happy if you leave a comment and set me straight. *disclaimer*
+
+My analogy has some tight <i class="icon-rest-coupling"> </i> coupling with the [HyperREST API icons](http://andreineculau.github.com/hyperrest-api-icons/) that I patched together a couple of weeks ago. The [Font Awesome icons](http://fortawesome.github.com/Font-Awesome/) came in like a glove.
+
+<i class="icon-api-entity"> </i> Entity
+
+<i class="icon-api-resource"> </i> Resource
+
+<i class="icon-api-representation"> </i> Representation
+
+<i class="icon-http-content-type"> </i> Content-Type
+
+<i class="icon-api-payload"> </i> Payload
+
+## Entity m:n Resource
+
+An <i class="icon-api-entity"> </i> entity may be your invoice (the concept, not the paper) for electricity for 2013 Mar 1-31st. The <i class="icon-api-resource"> </i> resource, on the other hand, holds your latest invoice. So the same resource, this inbox that you access every month, will link to some magical/undefined concept that is behind the curtains of the electrical company, that we refer to as *the invoice*.
+
+If you're stuck thinking in terms of URIs, here goes. There's `https://example.com/invoices/{id}` and then there's `https://example.com/invoices/latest`. Behind the curtains there's a DB, and there's a table called Invoices with a primary key `id`. While the `https://example.com/invoices/{id}` resource may have at times a 1:1 relation to the DB's Invoices\#{id} record, the resource that is identified by `https://example.com/invoices/latest` will not - it will link to a different entity, based on a variety of factors like the current timestamp, or the Authorization header, while maintaining its definition intact "the latest invoice".
+
+> The same <i class="icon-api-entity"> </i> entity can be used by multiple <i class="icon-api-resource"> </i> resources,
+and the same <i class="icon-api-resource"> </i> resource can use multiple <i class="icon-api-entity"> </i> entities.
+Neither the former, nor the latter, identifies the other.
+
+## Resource 1:n Representation
+
+"The latest invoice" <i class="icon-api-resource"> </i> resource can be represented by a webpage, an email message, a PDF document, a paper invoice, an electronic invoice in your online bank account, an audio invoice for the visually impaired, etc. These are all <i class="icon-api-representation"> </i> representations of the same concept, of the same resource.
+
+> The same <i class="icon-api-resource"> </i> resource can accept or provide multiple <i class="icon-api-representation"> </i> representations.
+*The same <i class="icon-api-resource"> </i> inbox can accept or provide multiple <i class="icon-api-representation"> </i> envelopes.*
+The latter does not identify the former.
+
+## Representation n:1 Content-Type
+
+These <i class="icon-api-representation"> </i> representations come with meta descriptors, <i class="icon-http-header"> </i> headers, to let you know how to interact with them. The <i class="icon-http-content-type"> </i> Content-Type header describes the content of the <i class="icon-api-representation"> </i> representation, in terms of semantics and syntax. `text/html` for a webpage, `application/pdf` for a PDF document, `audio/mp3` for audio content in MP3 format.
+
+> The content of multiple <i class="icon-api-representation"> </i> representations can be described by the same <i class="icon-http-content-type"> </i> Content-Type.
+*The content of multiple <i class="icon-api-representation"> </i> envelopes can be described by the same <i class="icon-http-content-type"> </i> cover.*
+The latter does not identify the former.
+
+## Representation n:1 Payload
+
+A <i class="icon-api-representation"> </i> representation without its <i class="icon-http-content-type"> </i> Content-Type is just a <i class="icon-api-payload"> </i> payload. A PDF document without a `application/pdf` <i class="icon-http-header"> </i> header, or say without the `.pdf` file extension, is just a binary file. A sheet of paper without indicators that it is an invoice, from the electricity company, etc. is nothing more than a sheet of paper with ink on it. That sheet of paper can be the support or the medium of an invoice sometimes, or a greeting card some other times.
+
+<i class="icon-api-representation"> </i> Representations of `application/json` or `application/json; charset=utf-16` types may share the same payload `{}`. Similarly, an integer, or a textual string, or a string representing a number in base 2, or base 10, may all be equaled to `11`.
+
+> Multiple <i class="icon-api-representation"> </i> representations can share the same <i class="icon-api-payload"> </i> payload.
+*Multiple <i class="icon-api-representation"> </i> envelopes can share the same <i class="icon-api-payload"> </i> letter.*
+The latter is part of the former.
+
+## TL;DR
+
+(<i class="icon-api-entity"> </i>)\* ~ <i class="icon-api-resource"> </i> = (<i class="icon-api-representation"> </i> = <i class="icon-http-content-type"> </i> + <i class="icon-api-payload"> </i>)\*
+
+---
+
+## Off-topic: Content-Type vs Media-Type
+
+Can anyone shed some light on the differences, if any?
+
+I tend to take `Content-Type` as referring to the HTTP header, and thus it can be `application/json; charset=utf-8`, while `Media-Type` refers to the {type, subtype} tuple alone, without the parameters - `application/json`. That's what you see in a [couple](http://msdn.microsoft.com/en-us/library/system.net.mime.contenttype.mediatype.aspx) of [places](http://restlet.org/learn/javadocs/2.1/gwt/engine/org/restlet/client/engine/header/ContentType.html) as well. But if you take a quick look at the HTTP specs though, you can clearly see that's an opinionated definition.
View
8 assets/strap-jekyll-default-custom.css
@@ -1,3 +1,5 @@
+@import url('//rawgithub.com/andreineculau/hyperrest-api-icons/v0.0.1/hyperrest-api-icons.css');
+
blockquote em {
display: block;
line-height: 20px;
@@ -8,14 +10,14 @@ blockquote em:before {
content: '\2014 \00A0';
}
-#post {
+#post .page-content {
text-align: justify;
}
-#post .twitter-tweet {
+#post .page-content .twitter-tweet {
margin: 25px auto !important;
}
-h2#comments {
+#post h2#comments {
visibility: hidden;
}
View
327 assets/strap-jekyll/css/strap-jekyll-default.css
@@ -42,7 +42,7 @@ a:hover > code {
/* Sidebar */
#sidebar {
- width: 370px; /* for when position:fixed */
+ width:370px; /* for when position:fixed */
}
#sidebar .sidebar-nav {
padding:9px 0;
@@ -62,7 +62,7 @@ a:hover > code {
}
#sidebar-footer iframe {
- border: 0px;
+ border:0px;
}
@@ -76,139 +76,140 @@ a:hover > code {
}
-/* List posts */
-#content ul.posts {}
-
-
-/* Post META */
-.post-meta .post-categories .btn-group button:not(.dropdown-toggle),
-.post-meta .post-tags .btn-group button:not(.dropdown-toggle) {
- cursor:default;
+/* Page META */
+span.page-meta {
+ margin-left:30px;
}
-span.post-meta {
- margin-left:30px;
+.page-meta .page-categories .btn-group button:not(.dropdown-toggle),
+.page-meta .page-tags .btn-group button:not(.dropdown-toggle) {
+ cursor:default;
}
-.post-meta .post-categories .btn-group,
-.post-meta .post-tags .btn-group {
+.page-meta .page-categories .btn-group,
+.page-meta .page-tags .btn-group {
opacity:0.25;
- filter: alpha(opacity=25);
+ filter:alpha(opacity=25);
}
-.post-meta .post-categories:hover .btn-group,
-.post-meta .post-tags:hover .btn-group {
+.page-meta .page-categories:hover .btn-group,
+.page-meta .page-tags:hover .btn-group {
opacity:1;
- filter: alpha(opacity=100);
+ filter:alpha(opacity=100);
+}
+
+.page-meta .page-date {
+ float:right;
}
-.post-meta .post-date {
- float: right;
+
+/* Page Comments */
+#page-comments {
+ margin:0 50px;
+ border-top:1px solid #eee;
}
+/* List posts */
+#content ul.posts {}
+
+
/* Single post */
-#post .post-meta {
+#post .page-meta {
margin-top:-20px;
margin-bottom:40px;
}
-#post .post-meta > div {
+#post .page-meta > div {
display:inline-block;
}
-#post .post-meta .post-categories > span,
-#post .post-meta .post-tags > span {
+#post .page-meta .page-categories > span,
+#post .page-meta .page-tags > span {
font-weight:bold;
}
-#post .post-meta .btn-group:hover ul.dropdown-menu {
+#post .page-meta .btn-group:hover ul.dropdown-menu {
display:block;
margin-top:0px;
}
-/* Post Comments */
-#post-comments {
- margin:0 50px;
- border-top:1px solid #eee;
-}
-
/* http://ivanzuzak.info/2011/02/18/github-hosted-comments-for-github-hosted-blogs.html */
.comment {
- background-color: transparent;
- border-color: #CACACA;
- border-style: solid;
- border-width: 1px;
- color: black;
- display: block;
- margin-bottom: 10px;
- margin-top: 10px;
- padding: 0px;
- width: 100%;
+ background-color:transparent;
+ border-color:#CACACA;
+ border-style:solid;
+ border-width:1px;
+ color:black;
+ display:block;
+ margin-bottom:10px;
+ margin-top:10px;
+ padding:0px;
+ width:100%;
}
.comment .commentheader {
- border-bottom-color: #CACACA;
- border-bottom-style: solid;
- border-bottom-width: 1px;
- color: black;
- background-image: -webkit-linear-gradient(#F8F8F8,#E1E1E1);
- background-image: -moz-linear-gradient(#F8F8F8,#E1E1E1);
- color: black;
- display: block;
- float: left;
- font-family: helvetica, arial, freesans, clean, sans-serif;
- font-size: 12px;
- font-style: normal;
- font-variant: normal;
- font-weight: normal;
- height: 33px;
- line-height: 33px;
- margin: 0px;
- overflow-x: hidden;
- overflow-y: hidden;
- padding: 0px;
- text-overflow: ellipsis;
- text-shadow: rgba(255, 255, 255, 0.699219) 1px 1px 0px;
- white-space: nowrap;
- width: 100%;
+ border-bottom-color:#CACACA;
+ border-bottom-style:solid;
+ border-bottom-width:1px;
+ color:black;
+ background-image:-webkit-linear-gradient(#F8F8F8,#E1E1E1);
+ background-image:-moz-linear-gradient(#F8F8F8,#E1E1E1);
+ color:black;
+ display:block;
+ float:left;
+ font-family:helvetica, arial, freesans, clean, sans-serif;
+ font-size:12px;
+ font-style:normal;
+ font-variant:normal;
+ font-weight:normal;
+ height:33px;
+ line-height:33px;
+ margin:0px;
+ overflow-x:hidden;
+ overflow-y:hidden;
+ padding:0px;
+ text-overflow:ellipsis;
+ text-shadow:rgba(255, 255, 255, 0.699219) 1px 1px 0px;
+ white-space:nowrap;
+ width:100%;
}
.comment .commentheader .commentgravatar {
- background-attachment: scroll;
- background-clip: border-box;
- background-color: white;
- background-image: none;
- background-origin: padding-box;
- border-color: #C8C8C8;
- border-style: solid;
- border-width: 1px;
- color: black;
- display: inline-block;
- float: none;
- font-family: helvetica, arial, freesans, clean, sans-serif;
- font-size: 1px;
- font-style: normal;
- font-variant: normal;
- font-weight: normal;
- height: 20px;
- line-height: 1px;
- margin-left: 5px;
- margin-right: 3px;
- margin-top: -2px;
- overflow-x: visible;
- overflow-y: visible;
- padding: 1px;
- text-overflow: clip;
- text-shadow: rgba(255, 255, 255, 0.699219) 1px 1px 0px;
- vertical-align: middle;
- white-space: nowrap;
- width: 20px;
+ background-attachment:scroll;
+ background-clip:border-box;
+ background-color:white;
+ background-image:none;
+ background-origin:padding-box;
+ border-color:#C8C8C8;
+ border-style:solid;
+ border-width:1px;
+ color:black;
+ display:inline-block;
+ float:none;
+ font-family:helvetica, arial, freesans, clean, sans-serif;
+ font-size:1px;
+ font-style:normal;
+ font-variant:normal;
+ font-weight:normal;
+ height:20px;
+ line-height:1px;
+ margin-left:5px;
+ margin-right:3px;
+ margin-top:-2px;
+ overflow-x:visible;
+ overflow-y:visible;
+ padding:1px;
+ text-overflow:clip;
+ text-shadow:rgba(255, 255, 255, 0.699219) 1px 1px 0px;
+ vertical-align:middle;
+ white-space:nowrap;
+ width:20px;
}
.comment .commentheader a:link {
- text-decoration: none;
+ text-decoration:none;
}
.comment .commentheader a:hover {
@@ -216,92 +217,92 @@ span.post-meta {
}
.comment .commentheader .commentuser {
- background-color: transparent;
- color: black;
- display: inline;
- float: none;
- font-family: helvetica, arial, freesans, clean, sans-serif;
- font-size: 12px;
- font-style: normal;
- font-variant: normal;
- font-weight: bold;
- height: 0px;
- line-height: 16px;
- margin-left: 5px;
- margin-right: 10px;
- overflow-x: visible;
- overflow-y: visible;
- padding: 0px;
- text-overflow: clip;
- text-shadow: rgba(255, 255, 255, 0.699219) 1px 1px 0px;
- white-space: nowrap;
- width: 0px;
+ background-color:transparent;
+ color:black;
+ display:inline;
+ float:none;
+ font-family:helvetica, arial, freesans, clean, sans-serif;
+ font-size:12px;
+ font-style:normal;
+ font-variant:normal;
+ font-weight:bold;
+ height:0px;
+ line-height:16px;
+ margin-left:5px;
+ margin-right:10px;
+ overflow-x:visible;
+ overflow-y:visible;
+ padding:0px;
+ text-overflow:clip;
+ text-shadow:rgba(255, 255, 255, 0.699219) 1px 1px 0px;
+ white-space:nowrap;
+ width:0px;
}
.comment .commentheader .commentdate {
- background-color: transparent;
- color: #777;
- display: inline;
- float: none;
- font-family: helvetica, arial, freesans, clean, sans-serif;
- font-size: 11px;
- font-style: normal;
- font-variant: normal;
- font-weight: normal;
- height: 0px;
- line-height: 33px;
- margin: 0px;
- overflow-x: visible;
- overflow-y: visible;
- padding: 0px;
- text-overflow: clip;
- text-shadow: rgba(255, 255, 255, 0.699219) 1px 1px 0px;
- white-space: nowrap;
- width: 20em;
+ background-color:transparent;
+ color:#777;
+ display:inline;
+ float:none;
+ font-family:helvetica, arial, freesans, clean, sans-serif;
+ font-size:11px;
+ font-style:normal;
+ font-variant:normal;
+ font-weight:normal;
+ height:0px;
+ line-height:33px;
+ margin:0px;
+ overflow-x:visible;
+ overflow-y:visible;
+ padding:0px;
+ text-overflow:clip;
+ text-shadow:rgba(255, 255, 255, 0.699219) 1px 1px 0px;
+ white-space:nowrap;
+ width:20em;
}
.comment .commentbody {
- background-attachment: scroll;
- background-clip: border-box;
- background-color: transparent;
- background-image: none;
- background-origin: padding-box;
- color: #333;
- display: block;
- margin-bottom: 1em;
- margin-left: 1em;
- margin-right: 1em;
- margin-top: 40px;
- overflow-x: visible;
- overflow-y: visible;
- padding: 0em;
- position: static;
- width: 96%;
- word-wrap: break-word;
+ background-attachment:scroll;
+ background-clip:border-box;
+ background-color:transparent;
+ background-image:none;
+ background-origin:padding-box;
+ color:#333;
+ display:block;
+ margin-bottom:1em;
+ margin-left:1em;
+ margin-right:1em;
+ margin-top:40px;
+ overflow-x:visible;
+ overflow-y:visible;
+ padding:0em;
+ position:static;
+ width:96%;
+ word-wrap:break-word;
}
.comment .commentbody p {
- margin-bottom: 0.5em;
- margin-top: 0.5em;
- margin-left: 0em;
- margin-right: 0em;
+ margin-bottom:0.5em;
+ margin-top:0.5em;
+ margin-left:0em;
+ margin-right:0em;
}
.comment .commentbody pre {
- border: 0px solid #ddd;
- background-color: #eef;
- padding: 0 .4em;
+ border:0px solid #ddd;
+ background-color:#eef;
+ padding:0 .4em;
}
.comment .commentbody pre code {
- border: 0px solid #ddd;
+ border:0px solid #ddd;
}
.comment .commentbody code {
- border: 1px solid #ddd;
- background-color: #eef;
- font-size: 85%;
- padding: 0 .2em;
+ border:1px solid #ddd;
+ background-color:#eef;
+ font-size:85%;
+ padding:0 .2em;
}
View
4 assets/strap-jekyll/js/strap-jekyll-comments-github.js
@@ -13,7 +13,7 @@
cbody,
url;
- url = $('#post-comments-url').attr('href');
+ url = $('#page-comments-url').attr('href');
for (i = 0; i < data.length; i++) {
cavatar = data[i].user.avatar_url;
@@ -40,7 +40,7 @@
cbody +
'</div>';
- $('#post-comments-placeholder').append('<div class="comment">' +
+ $('#page-comments-placeholder').append('<div class="comment">' +
cheader +
cbody +
'</div>');

No commit comments for this range

Something went wrong with that request. Please try again.