API Request/Response
From ePrize Developers Wiki
(→XML media type) |
|||
| (16 intermediate revisions not shown.) | |||
| Line 1: | Line 1: | ||
| - | + | {{Logo}} | |
| - | + | All HelloWorld Web Services 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 HelloWorld Web Services uses that further simplify the programming. | |
| - | The {value} is part of the URL and must be encoded using standard URI encoding when the value contains reserved or non-ASCII characters. Values must be valid UTF-8 before being URI encoded. The server will decode the URI encoding, then decode the octet sequence as UTF-8. Arbitrary binary data is not allowed and may cause a 400 error. | ||
| - | + | == Follow the URLs == | |
| - | This | + | Do not try to deconstruct URLs returned as resources by HelloWorld Web Services. 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 HelloWorld Web Services. |
| - | + | == 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 HelloWorld 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 HelloWorld Web Services 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 HelloWorld Web Services 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, HelloWorld Web Services can accept your key:value pairs in a request in any order. | ||
== XML media type == | == XML media type == | ||
| - | + | Currently HelloWorld Web Services supports XML responses for all API calls. Partial support for JSON and YAML has been implemented as a [[beta feature]]. 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. | ||
| + | |||
{| border="1" | {| border="1" | ||
|- | |- | ||
| - | | | + | |key: {value} |
| - | |< | + | |<key>{value}</key> |
|- | |- | ||
| - | | | + | |key: {resource} |
| - | |< | + | |<key href="{resource}" /> |
|- | |- | ||
| - | | | + | |keys: [{value1}, {value2}] |
| - | |< | + | |<key>{value1}</key><br/><key>{value2}</key> |
| - | < | + | |
|- | |- | ||
| - | | | + | |key: [attr1: {value1}, attr2: {value2}] |
| - | |< | + | |<key><br/><attr1>{value1}</attr1><br/><attr2>{value2}</attr2><br/></key> |
| - | < | + | |
| - | < | + | |
| - | </ | + | |
|} | |} | ||
| + | |||
| + | == Watch Out For... == | ||
| + | |||
| + | === Empty POST Requests === | ||
| + | |||
| + | POST requests without any form data my be blocked by firewalls. This can lead to unexpected problems along the way. To avoid this problem, or if you think you may be experiencing this -- add a parameter name and value to your POST data. foo=foo will work just fine. | ||
| + | |||
| + | === Redirects === | ||
| + | |||
| + | Some of the resources that create records (such as: [[Create_profile|create profile]] or [[Award_token|award token]]) provide a Location: response header to indicate a resource for the record that was created. Some user agents will automatically follow the redirect to this Location and it will appear that the header is missing. If that is the case, look at the Request URI after the redirect -- or attempt to disable the redirect in your user agent. | ||
Current revision
All HelloWorld Web Services 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 HelloWorld Web Services uses that further simplify the programming.
Contents |
Follow the URLs
Do not try to deconstruct URLs returned as resources by HelloWorld Web Services. 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 HelloWorld Web Services.
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 HelloWorld 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 HelloWorld Web Services 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 HelloWorld Web Services 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, HelloWorld Web Services can accept your key:value pairs in a request in any order.
XML media type
Currently HelloWorld Web Services supports XML responses for all API calls. Partial support for JSON and YAML has been implemented as a beta feature. 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> |
Watch Out For...
Empty POST Requests
POST requests without any form data my be blocked by firewalls. This can lead to unexpected problems along the way. To avoid this problem, or if you think you may be experiencing this -- add a parameter name and value to your POST data. foo=foo will work just fine.
Redirects
Some of the resources that create records (such as: create profile or award token) provide a Location: response header to indicate a resource for the record that was created. Some user agents will automatically follow the redirect to this Location and it will appear that the header is missing. If that is the case, look at the Request URI after the redirect -- or attempt to disable the redirect in your user agent.
