API Request/Response
From ePrize Developers Wiki
All eWS requests follow the HTTP conventions for formatting the URL and request headers. All compliant HTTP programming libraries will be able to send a request and receive a response. In addition, there are some other conventions that eWS uses that further simplify the programming.
Contents |
Follow the URLs
Do not try to deconstruct URLs returned as resources by eWS. All resources are designed to be passed around as URLs—you will never need to take apart a URL to use it with another API. This also makes it much easier to upgrade to future versions of eWS.
Canonical URLs
The URL returned in the Location header of a factory resource should be kept as the canonical identifier for that resource. These canonical URLs are safe to store in your systems because ePrize guarantees that the URL formats will not be changed without at least one year of advance warning. Our intention is to honor the canonical URLs forever.
In addition to future proofing your system, the canonical URLs are secure to automated attack because they are difficult to guess. This provides similar protection to passwords as long as you take care to keep the canonical URLs private. If you can't keep them private, at least follow industry best practices for cookie storage when storing them on consumer computers.
Canonical URLs never redirect.
Asymmetric Data Access
Untrusted clients will not be able to retrieve all the information that they send. This is most visible in profile registration where a complete profile including PII may be sent, but only a safe PII-free version of the profile may be fetched back. Untrusted clients also have less access to the eWS API.
UTF-8 Everywhere
All information sent in both directions must be UTF-8. All information, especially consumer provided content, formatted into a URL must be encoded in UTF-8 prior to being URI encoded. The final URL before being submitted to eWS must be plain ASCII and compliant with HTTP 1.1.
When the server accepts a URL, form posting, or other client provided information, the information is always URI decoded, then the octet stream decoded as UTF-8. If an error occurs during this process, the server may not be able to generate a precise error and will simply return "400 Bad Request".
The only exception to the UTF-8 everywhere rule is in file upload. Certain resources may accept image, video, sound or other formats with their own standard formats. In every case, if a non-UTF-8 format is allowed, all legal formats will be listed.
Maximum Sizes
The maximum length of most values in a key:value pair is 1000 octets after URI encoding. Exceptions will be listed. This maximum applies regardless whether the value is formatted in a URL or form posting.
No Guaranteed Key:Value Ordering
The order of keys in the response may change. Likewise, eWS can accept your key:value pairs in a request in any order.
XML media type
Eventually eWS will support multiple media types as responses. This will allow you to choose the type that is easiest for your system to work with. JSON for example is very compatible with AJAX; XML is easy to work with in Groovy.
XML is not a serialization format, but we try to follow the following conventions when reading or writing structure information.
| key: {value} | <key>{value}</key>
|
| key: {resource} | <key href="{resource}" /> |
| keys: [{value1}, {value2}] | <key>{value1}</key> <key>{value2}</key> |
| key: [attr1: {value1}, attr2: {value2}] | <key> <attr1>{value1}</attr1> <attr2>{value2}</attr2> </key> |
