EWP Echo API might seem trivial in itself, but it requires EWP developers to design and test the authentication and security framework which they will use throughout the development of all the other EWP features. It is RECOMMENDED for all developers to implement it (and keep it updated) at least in their development EWP Hosts, to avoid potential problems in the future.
It also familiarizes developers with the way EWP APIs are documented (many important parts are documented in XSD files!).
This version of this API uses standard EWP Authentication and Security, Version 2. Server implementers choose which security methods they support by declaring them in their Manifest API entry.
Since Echo API is implemented primarily for testing everyone's security framework, servers are RECOMMENDED to support all currently specified standard authentication and encryption methods, with some minor exceptions:
-
It is FORBIDDEN to support Anonymous Clients in Echo API.
-
If you (the server implementer) are certain that you won't be supporting some particular security method in any of your other APIs, then it's okay to "skip" supporting this method in Echo API too. (This is especially true in case of TLS Client Certificate Authentication, which - based on the input from EWP developers - turned out to be difficult to implement in some architectures).
-
When new security methods are introduced in the future, it's usually okay to "lag behind" a little. That is, you usually won't be required to support new security methods immediately after they are introduced. However, in time, some older security methods MAY get deprecated, or even banned - which might result in you getting cut off from the rest of the EWP Network (first, you may get banned by some more restrictive partners, and later on, by the Registry Service administrators). So you should keep an eye on that!
It is also RECOMMENDED that you support all these security methods at a single endpoint/URL (as opposed to having separate API-entries in your manifest, per each possible combination of security methods). At the time we are writing this, all standard methods are designed in a way that enables them to be used interchangeably on single URL (and we hope it will stay this way).
Requests MUST be made with either HTTP GET or HTTP POST method. Servers MUST support both these methods.
Hint: You MAY support other encodings (such as multipart/form-data), but
you are not required to. As described in the general error handling
rules, you SHOULD respond with a HTTP 415 error status if
you receive a POST in an encoding which you don't support.
Parameters MUST be provided either in a query string (for GET requests), or in
the application/x-www-form-urlencoded format (for POST requests). Servers
MAY reject all other formats.
Servers MUST retrieve echo values (plural) from request. The echo parameter
is repeatable. It means that it can appear more than once (e.g.
url?echo=...&echo=...). Such repeatable parameters will be used throughout
other EWP APIs, so you should be able to retrieve them properly.
Optional means, that the list of echo values is allowed to be of
zero-length. It is valid to call the echo URL with no echo parameters.
-
General error handling rules apply. (This means that you MUST follow these rules. These apply to most of the other EWP APIs too.)
-
Usually APIs will describe much more rules here. E.g. which combinations of parameters should result in which kind of error, etc. However, in case of Echo API, you will need to support only the "general cases".
Servers MUST respond with a valid XML document described by the response.xsd schema. See the schema annotations for further information.
The last requirement is to publish the URL of your Echo API implementation in your Manifest file, so that other developers (and, possibly, continuous integration scripts, like the Echo API Validator) may discover and test it.
The format of the Echo API manifest entry is described in the
manifest-entry.xsd file. You will need to use a proper
xmlns when you are including it in your manifest file.
Note, that this deployment step looks exactly the same for all APIs, so in most cases API designers skip it in their API specifications.