Trading API calls that return large amounts of metadata such as GetCategories can result in the API application waiting a relatively long time for the results to come back. Applications that run on clients that do not use broadband internet connections are even more severely affected. In an effort to shrink the amount of data returned by Trading API calls, eBay has implemented the use of compression for the Trading API.
Q: How do I request compressed content?
A: Simply by setting an HTTP header. The header to set is "Accept-Encoding" and the value to set this header to is "gzip". It's no different than setting the header for the DetailLevel and the other required headers when making an API call, so if you are able to make API calls before implementing compression, you already know how to set headers.
Example: Here's the syntax when using the MSXML ServerXMLHTTP library (all other languages and libraries follow much the same syntax):
oServerXMLHTTP.setRequestHeader "Accept-Encoding", "gzip"
Q: If I request compressed content, do I always get back compressed content?
A: If compressed content is requested, and the API call results in more than 500 bytes and less than 7.5 Megabytes of uncompressed data to be returned to the caller then the data will be returned compressed, otherwise the data will be returned uncompressed. These boundary values are subject to change, and we will do our best to have a process that documents the current boundary values. Our recommendation is that you only use compression for the following API calls:
We may add more API calls to this recommendation list in the future.
Q: How do I handle the compressed content when I get it back from the API?
A: The best place to go for information on decoding compressed data is at http://www.gzip.org/zlib/
The actual download links are in the section beginning with the sentence "The current release is publicly available here". All decompression functions require the initial size of the content (size of data before compression). The initial size of the content returned by an eBay API call that has compressed content is stored in the last 4 bytes of the response. Extract this data into a long type and pass the value to the decompression function as the interface dictates.
The C libraries present are cross platform and can be used in a non-Microsoft environment to build the zlib interface. Please see the README folder in the top level directory where you unzipped the package to for more information.
Please be aware that the "zlib compiled DLL" available here uses the CDECL calling convention, so it cannot be used directly by Visual Basic or other development languages that can only interface to DLLs that use the STDCALL (Win32 API) convention. There is detailed documentation about the compiled DLL in the DLL_FAQ.txt file in the win32 folder of the package. However, for languages such as VB and Perl on a Windows Platform there is a solution for STDCALL interfaces in the /contrib/vstudio folder. The contrib folder contains a few other interfaces as well.
Using web search engines for "using zlib in xxx" where xxx is perl, java, whatever language you prefer will also turn up useful sites, such as this one that has a pure Java implementation of zlib: