API Quick Start Guide
Welcome to AfterMarket.pl API documentation. If you are here for the first time, please take some time to read this document. It will get you familiar with the API concepts and will allow you to start using the API successfully.
What is the AfterMarket.pl API?
The AfterMarket.pl API is a robust Application Programming Interface which allows you to perform common marketplace functions programmatically. For example, you can use the API to write simple applications that perform operations such as:
List many auctions on the marketplace at once.
Modify listing prices for multiple domains.
Automatically submit counteroffers for received purchase offers.
And so on...
To use the API, you need some programming knowledge, because it requires custom programming to call the appropriate API functions. The API can be used in any language that is able to call SOAP Web services, so the choice of programming language is left to you.
Calling API functions
The AfterMarket.pl API is available as a SOAP Web service. To call the API functions, you need to connect to the following WSDL URL:
https://am-soap.com:4192/service.php?class=AfterMarket&wsdl
To learn about all the API functions, view the documentation for the AfterMarket class. It is the main API class, where all the API functions are defined. Each public method of this class is callable via SOAP.
User authentication
All API functions require two parameters: "email" and "key". The first one is the email of the user making the request. The user must be registered on the AfterMarket.pl website; no user creation API is present at the moment.
The second parameter is the authorization key. It can be created by calling the login() function, which requires user email and password. Upon successful execution, it returns the authorization key to be used in subsequent requests. The key can be be invalidated by using the logout() function. It will alsa expire automatically after 30 minutes of inactivity. You can use the keepAlive() function to prevent the session from expiring.
You can have a maximum of 10 open sessions. If you try to open more, the previous ones will automatically be closed.
You can issue a maximum of 10000 API requests per day on a single account, regardless of the open sessions. If you need a higher limit of commands, please contact us.
API conventions
Several conventions are used throughout the API.
Active functions
Active functions are functions which change the marketplace state. They include placing a bid in an auction, listing a new auction, changing a listing price, etc. An example of an active function is the placeBid() function.
Such functions have always a third parameter named "check". This parameter selects between two distinct operation modes of the function:
When the value equals "true", the function performs only parameter validation. The parameters are checked for all possible error conditions, such as invalid values, insufficient balance on the account, and so on. If any error occurs, the function throws an appropriate exception. Otherwise, it just returns an empty value.
When the value equals to "false", the function is executed normally (i.e. it performs the desired operation).
Please note that even if the function with "check" parameter set to "true" succeeds, it is not a guarantee that it will succeed with it set to "false". This is because some error conditions can only happen with full function execution (for example, errors from the underlying domain registry).
Listing functions
Listing functions are functions which return a list of objects describing some marketplace objects (auctions, bids, offers and so on). An example of an active function is the getCategories() function.
For each listing function, there is always an additional function which returns the number of elements in the list. It allows the API user to learn how many object are expected in the actual function reply, and behave accordingly (for example, with a Web application, this information can be used to support paging). These functions follow common naming conventions, for example for the function getCategories(), it is named getCategoriesCount().
Most listing functions support paging, to prevent from returning a large list. Two paging parameters, "start" and "size", define the (zero-based) starting element and number of elements to retrieve. Consult the function getReceivedOffers() for an example. Please note that a maximum page size if 1000 elements.
Listing functions can also include the "order" parameter, which defined how the list is sorted. It is a string with comma-separated names of fields used for sorting, with either a "+" or "-" sign appended (denoting ascending or descending order). The field names correspond to the properties of objects returned by the function; if a name is given that does not exist in the returned object, it is ignored. Consult the API Code Samples article to see how list sorting is implemented.
Error codes
A set of error codes has been defined, to allow the API user to distinguish between various error conditions and act accordingly. To learn about error codes, review the API Error Codes document.
Timestamp values
Time values (such as auction end time, or offer submission time) are always returned as a Unix timestamp (the number of seconds since the Unix epoch, January 1 1970). See this Wikipedia article for the discussion of the Unix timestamp standard. In Unix-derived languages (such as C, C++, PHP, Perl), there are several functions to display and manipulate the timestamps. You can also use the formatTime() function to retrieve a textual representation of a given timestamp.
All times are expressed in Central European timezone, which is GMT+1.
