Difference between revisions of "REST API/Considerations"
From AgileApps Support Wiki
imported>Alice |
imported>Aeric m (Text replace - '[[Role Based Access' to '[[Data Access') |
||
| Line 5: | Line 5: | ||
:* The content types for request data are <tt>application/xml</tt> and <tt>application/json</tt>.<br>(<tt>text/xml</tt> is ''not'' supported.) | :* The content types for request data are <tt>application/xml</tt> and <tt>application/json</tt>.<br>(<tt>text/xml</tt> is ''not'' supported.) | ||
:* It is necessary to login to the platform before making a REST API call (and logout afterwards) | :* It is necessary to login to the platform before making a REST API call (and logout afterwards) | ||
:* All REST API calls execute within the context of the [[User]] that is logged in. As with all UI actions, this means that any subsequent REST API calls (to access levels, data visibility, team membership, etc.), are governed by the [[ | :* All REST API calls execute within the context of the [[User]] that is logged in. As with all UI actions, this means that any subsequent REST API calls (to access levels, data visibility, team membership, etc.), are governed by the [[Data Access Permissions]] granted to the User. | ||
:* REST API calls are broadly categorized as Data API or Metadata API (excluding login/logout) | :* REST API calls are broadly categorized as Data API or Metadata API (excluding login/logout) | ||
:* Data calls can span multiple objects, for example, the ''owner'' field in an object, or [[Lookup]]s (foreign key relationships) to some other objects | :* Data calls can span multiple objects, for example, the ''owner'' field in an object, or [[Lookup]]s (foreign key relationships) to some other objects | ||
Revision as of 01:37, 16 October 2012
- The REST APIs are granular (each call operates on a single entity)
- Each REST API call is treated as a single transaction
- In most cases, APIs have a direct one-to-one mapping with the UI
- Data input and output can be in either XML or JSON format.
- The content types for request data are application/xml and application/json.
(text/xml is not supported.) - It is necessary to login to the platform before making a REST API call (and logout afterwards)
- All REST API calls execute within the context of the User that is logged in. As with all UI actions, this means that any subsequent REST API calls (to access levels, data visibility, team membership, etc.), are governed by the Data Access Permissions granted to the User.
- REST API calls are broadly categorized as Data API or Metadata API (excluding login/logout)
- Data calls can span multiple objects, for example, the owner field in an object, or Lookups (foreign key relationships) to some other objects
- The REST API implements the database CRUD model (Create, Read/Select, Update, Delete) using HTTP protocol requests (POST, GET, UPDATE and DELETE).
CRUD Action HTTP Method Create POST Read/Select GET Update PUT Delete DELETE
- Field elements are optional in record updates. If a field is missing, existing data in that field is unaffected. If a field is present, but empty, any existing data in that field is deleted.
- When the database value for a checkbox field is null, the REST API returns 0. (So the value is always 1 (checked) or 0 (unchecked), whether or not the field has been initialized.)
Note:
When specifying a URL in code, any special characters (characters other than letters and numbers) need to be encoded. For example, a space character can be encoded using either + or %20.(Browsers typically take care of encoding URLs entered into the address bar--so the URL displayed after visiting a page may differ somewhat from the one that was initially entered.)
Here are some typical encodings:
space
+
%%20 or +
%2B
%25
So:
Instead of Use & (A&B)
space (A B)%26 (A%26B)
%20 (A%20B)
It can be hard to get be hard to get the encoding right, so it's desirable to use a language library designed for the purpose.
Learn more:- URL Encoding in HTML
- Encode a URL in JavaScript
- URLEncoder class for Java
