REST Comparison

	A	B	C	D	E	F	G	H	I
1							(Speculative circa Mar 2014; not a commitment)
2	Service	Highrise/37Signals	Salesforce/Force.com	Github	Drupal 8	Civi APIv3	Civi 5.0 (Ideal)	Civi 5.0 (Preview)	Civi 5.0 (Early/Mid-Mar)

3	General: Description	CRM-focused REST API. Consumer-oriented docs.	Customizable datastore with REST API. Consumer-oriented docs.	Git-focused REST API. Consumer-oriented docs.	Customizable datastore with REST API. Provider-oriented docs.
4	General: Doc URL	https://github.com/basecamp/highrise-api	https://www.salesforce.com/us/developer/docs/api_rest/	http://developer.github.com/v3/
5	Formats: API Versioning	None	Diff REST URLs per version	Header (Accept:)	None	Query param (?version=)	?	?	None
6	Formats: Media Types	XML	JSON, XML	JSON	{JSON,XML}{,HAL}; extendable	JSON,XML	JSON,XML	JSON,XML	JSON,XML
7	Formats: Media Type Signaling	URL-ext (“.xml”)	Header("Accept:") or URL-ext (“.xml”)	None	Header (Accept:)	Query param (?json=)	Header ("Accept:") or query param (?_format=)	Header ("Accept:") or query param (?_format=)	Header ("Accept:") or query param (?_format=)
8	Formats: Pretty Printing	No(?)	Header (X-PrettyPrint:)	No(?)	?	No	Param (?_pretty=true)	No	No
9	Formats: Mutator Responses	Full data (with ?reload=true)	Summary data (id/errors)	Summary data (errors)	?	Inconsistent unless options.reload=true	Full data (with ?_return=true)	Full data (with ?_return=true)	Summary data (errors, plain-text)
10	Authn: OAuth2	Yes	Yes	Yes	Yes	No	Yes	No	No
11	Authn: HTTP Basic Auth	No	No	Yes	Yes	No	Yes	No	No
12	Authn: Other	Custom token (retrievable with user+pass)			Extendable	CMS session; custom-token	CMS session; custom-token; extendable	CMS session	CMS session
13	Authz: Entity-level	?	Yes(?)	No	Yes	Yes	Yes	Yes	Yes
14	Authz: Field-level	No	Yes(?)	No	Partial (“Views”)	Partial (ACLs+Profiles)	Partial (ACLs+Profiles)	No	No
15	Authz: Record-level	Yes	Yes(?)	Yes	No (Extendable)	Partial (ACLs; Extendable)	Partial (ACLs; Extendable)	Partial (ACLs; Extendable)	No (Extendable)
16	Verbs: GET	Read	Read	Read	Read	Read	Read	Read	Read
17	Verbs: POST	Create-only	Create; Verb emulation (?HttpMethod)	Create; Update; Custom-actions	Create	Any action	Create; Update	Create; Update	Create; Update
18	Verbs: PUT	Update (with “-123” to unset)	No	Replace	No	No	Replace	No	No
19	Verbs: PATCH	No	Update (Bare JSON)	Update (Bare JSON)	Update (Bare JSON)	No	Update (Bare JSON; x-www-form; JSON-Patch)	Update (Bare JSON)	Update (Bare JSON)
20	Verbs: DELETE	Delete	Delete	Delete	Delete	No	Delete	Delete	Delete
21	Schema: Reflection	No	Yes (“sobject” resource)	No	?	Yes (“getfields”)	Yes (JSON Schema)	Yes (JSON Schema)	No
22	Schema: UI	No	?	No	Partial (Field + Views Admin not REST-aware; restui not field-aware)	Yes (API Explorer)	Yes (JSON Editor)	No	No
23	Schema: Docs	Yes	No	Yes	No	No	Yes	No	No
24	Schema: Docs: Examples	Yes	No	Yes	No	Yes	Yes	No	No
25	Get: Filters	Query Param (“&criteria[state]=CA”)	Single-field (in path) or complex (filtered SOQL)		Yes (With Views REST)	Query param or JSON param	Query Param; Complex Query (Filtered DQL)	Query param	Query param
26	Get: Specify Return Values	?	Yes	No, but diff btwn “Summary” and “Detail” representations	No(?), but Views allows diff representations	Yes (Properties, Chaining)	Yes (Properties, HAL Relations)	Yes (HAL Relations)	No
27	Get: Other comments				Support for “content” and “views” (saved queries).
28	Relations (Contact<->Email/Phone, Read)	Embedded	?	Sub-resource (collection item)	FK(id) + Views + HAL(?)	FK (id) + Chaining	FK (id) + HAL	FK (id) + HAL
29	Relations (Contact<->Email/Phone, Write)	Embedded. If specified, replaces old list	?	Sub-resource (collection item)	FK(id)	FK (id) + Chaining	FK (id) + HAL. If HAL specified, replaces old list	FK (id) + HAL. If HAL specified, replaces old list
30	Relations (Contact<->Activity, Read)	FK (id)	?	Embedded (“Summary”, with id+username+urls)	FK(id) + Views + HAL(?)	FK (id) + Chaining	FK (id) + HAL	FK (id) + HAL
31	Relations (Contact<->Activity, Write)	FK (id)	?	Username string	FK(id)	FK (id) + Chaining	FK (id)	FK (id)
32	Relations (Contact<->Custom Data)	Embedded <subject-data>	Native-like	None	Native-like	custom_123 (sometimes); CustomValue (anytime).	HAL (SV/MV); Entities (MV)	?	None
33	Cross-Site: CORS	?	No (requested/speculated)	Yes (Registered OAuth links)	?	No	Yes	No	No
34	Cross-Site: JSON-P	?	Yes (with authtoken)	Yes (for GET)	?	No	Maybe (With special token handling)	No	No
35	Cross-Site: crossdomain.xml	?	Yes	No(?? - master-only + empty)	?	No	Yes	No	No
36	Batch Operations	No(?)	No(?)	No(?)	No(?)	Yes (chaining & batching)	“Batch” resource; HAL relations	?	No
37	Sane Option Values (eg country "1228" vs "us")	Yes				Yes (Partial?)	Yes	?	No
38	Optimistic locking	?	?	?	?	No	Yes	?	No
39	Multilingual	?	?	?	?	Yes	Yes	?	No
40	Other Notes			Requires User-Agent	(?) Consolidated request lifecycle for REST/HTML/forms		All options should work as headers (“X-PrettyPrint:”), query params with “_” prefix (“?_pretty=1”), or embeds ({_options:{pretty:true}}})	All options should work as headers (“X-PrettyPrint:”), query params with “_” prefix (“?_pretty=1”), or embeds ({_options:{pretty:true}}})
41	Resource Type: Contact / Person / Org / Email / Phone / Address	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Partial
42	Resource Type: Activity / Participant / Contribution / Membership	Yes	Yes	N/A (Comparable)	N/A (Extendable)	Yes	Yes	Yes	Partial
43	Resource Type: Report	No	?	No	Yes (Views)	Yes	Yes	Yes	No
44	Resource Type: Custom Fields	Yes	?	No	?	Yes	Yes	Yes	Partial
45	Subjective: Coolest Feature (Tim's opinion)	Predictable. Clear docs.	SOQL. Field-level security.	Cross-site (browser-based) integrations	Views; Extensibility; Consolidated request lifecycle	Chaining. REST+JS+PHP+Smarty+Drush
46	Subjective: Biggest Liability (Tim's opinion)	Old RESTful interface (eg XML+POST); not like the Cool New RESTful (eg JSON+PUT/PATCH)	Data model depends on site. Hard to document.		Data model depends on site. Hard to document. Moving target following the cool kids.	BAOs. Old RESTy interface. Unusual authentication.