The following are potential characteristics, issues for consideration, or facets, of API specification.
-
Meaningful (short) URIs, or at least understandable
-
RESTful purity -- CarrotVsOrangeDiscuss
-
GET/POST
-
GET/PUT/DELETE/POST
-
Protocol level -- HTTP (REST), SOAP (REST with SOAP wrapper), XML-RPC
-
service location
-
introspection -- the server provides a summary of interaction
-
late binding -- trying features and resubmitting according to their responses
-
explicit endpoints in the XML -- like introspection, but in every <feed>, <entry>, etc.
-
auto-discovery -- like explicit endpoints in the XML, but via their <link>
-
XML id vs. URI
-
<id> vs. <endpoint> -- <endpoint> is (logically, could be <id>) the URI where actions occur, and corresponds exactly to the 'Location:' returned when POSTing to create a dynamically created resource; <endpoint> is "the XML" where <link> is typically (X)HTML
-
<id> is a GUID vs. <id> is a actionable URI
-
API is resource entity independant, ie. does not depend on XML or actions contained within transferred entities.
-
permanency
-
are <link>s or retrievable <id>s "always there"
-
do/must location-based URI scheme <id>s change if their host location changes
-
URI vs. compound identifier (base URI + relative URI, where "relative URI" is the effective identifier)
-
use of non-retrievable URIs (not 'http:') for identifiers (<id>)
-
"comment" is not defined by its data model or relation, just that it uses only POST to create (no named comments using PUT creation)
-
MOVE, COPY, LOCK, UNLOCK, MKCOL (mkdir) from WebDAV
-
URI-space layout
-
path-based URIs (blog/entry/1) vs query-based URIs (blog?entry=1)
-
for public browsing
-
for maintenance using API (blog/entry/1?asXML)
Contributors: Arien, BillKearney, JeremyGray, JoeGregorio, KenMacLeod, NickChalko