API versions

Stable versions of the API are released once or twice a year, and do not change after they have been released. The stable version is used to create a separate version with the “Live” label, such as “Live 4”. It is developed in step with new Yandex.Direct features, so changes are introduced in the Live version about once a month.

It is safe to move from the stable version to the Live version, since the Live version supports all the formats of the stable version, but the opposite is not true.

Choosing between Live and stable versions

In most cases, we recommend using the last stable version (with the highest number) and moving to this version from previous versions. The Live version is intended for users who are interested in accessing new Yandex.Direct features via the API as soon as possible, and who can adapt their software to the changing format of requests and responses.

It is not difficult to move from the stable version to Live, since the format of the stable version can be used for interacting with the Live version. The API automatically determines which version the client is using, and selects the appropriate algorithm for handling data.

Responses in the Live version use the newest relevant format. However, Live maintains a strict policy of "the response should be clear to stable version clients". This means that any changes to the Live response format enhance the stable version format but do not break it. This is a guarantee that a client of the stable version will get the expected parameters, although their values might be unknown to it. Similarly, responses in Live may contain new parameters that a stable version client can ignore.

Recommendations for using the Live version

Changes are introduced in the Live version without notifying users. The main source of information about changes is the newsletter (you can subscribe in the Yandex.Direct interface on the "Direct API access management" page).

Below are listed typical changes in the Live version along with recommendations for improving adaptability of client programs.

1. New parameter value. An unknown value might cause ambiguity in the program and incorrect data handling. We recommend putting a check in the program's algorithm that will cancel data handling in this case and notify the developers of the new value.

2. A new parameter in the response. If the program is familiar with the Live format, it will correctly handle new parameters; otherwise, it ignores them. Ignoring new parameters does not lead to errors, since it is only a refusal to use new features (they are added to the Live version in a way that does not affect existing functions).

   

   If the program generates an API request and does not include mandatory parameters in the request (because they are not known to the program), the values of these parameters in the database may be changed to pre-set values. To avoid this, we recommend using the technique described in point 3.

3. The CreateOrUpdateCampaign

   [no-highlight[ Creates a campaign with the specified parameters, or changes the parameters of an existing campaign. more CreateOrUpdateCampaign ]no-highlight]

   , CreateOrUpdateBanners

   [no-highlight[ Creates an ad or edits the parameters of an existing ad. more CreateOrUpdateBanners ]no-highlight]

   and UpdateClientInfo

   [no-highlight[ Changes a user‘s personal data and permissions. more UpdateClientInfo ]no-highlight]

   methods expect to get a different set of data than the one the program generates.
   Before modifying parameters for campaigns, ads or clients, it is a good idea to get the current parameters from the API via the GetCampaignParams

   [no-highlight[ Returns the campaign parameters. more GetCampaignParams ]no-highlight]

   , GetBanners

   [no-highlight[ Returns ad parameters. more GetBanners ]no-highlight]

   and GetClientInfo

   [no-highlight[ Returns the user‘s personal data. more GetClientInfo ]no-highlight]

   methods. These methods return a set of parameters in the Live version format. You will only have to change parameter values where necessary in the structures, and input these structures to the methods being edited.