API Changelog

Dec. 4 2018 - preannounce

Media upload (POST /medias.xml)

Additional structure in XML response

A media upload will return the UUID of newly created media in <media>/<uuid>. Current field <media-uuid> will remain for a while, but will be deprecated. Please make sure that your current code can accept this additional <media> structure in the API response. Example of such reply that will be returned:

<?xml version="1.0" encoding="UTF-8"?>
<reply>
  <media>
    <uuid>8a2da7da-0d02-4b72-b0ab-6f97216cf95a</uuid>
  </media>
  <media-uuid>8a2da7da-0d02-4b72-b0ab-6f97216cf95a</media-uuid>
  <location>/medias/8a2da7da-0d02-4b72-b0ab-6f97216cf95a.xml</location>
  <message>Successfully uploaded.</message>
  <request>POST /medias.xml</request>
</reply>

Transitioning to a new upload scheme

The upload API will start supporting direct upload to cloud provider(s). The initial POST request will return upload details in addition to the new <uuid> field. Full details will be available in the online documentation.

Uploading directly to the storage cloud provider is not just a new option, it is what we're progressively transitioning to: uploading to our servers will still be supported for some times to both ensure a progressive move and give you a good opportunity to update your application accordingly, but upload speeds and processing capacity will progressively be reduced.

Therefore you shouldn't postpone updating your application too much, especially if you upload large volumes.

Gallery creation (POST /websites/.../galleries.xml)

Same as media upload: UUID of newly created galleries will move to <gallery>/<uuid> Make sure that your current code can accept this additional <gallery> structure in the API response.

Details of newly created gallery will also be directly provided in the additional structure, so that a subsequent API call to retrieve details of the newly created gallery is not required anymore. Example:

<?xml version="1.0" encoding="UTF-8"?>
<reply>
<gallery-uuid>f95eee28-f2ff-45fd-9d91-8c534894bd9b</gallery-uuid>
<gallery>
<uuid>f95eee28-f2ff-45fd-9d91-8c534894bd9b</uuid>
<name>New gallery</name>
<url-path>new-gallery</url-path>
<full-url-path>galleries/new-gallery</full-url-path>
<description nil="true"/>
<medias-count>0</medias-count>
<full-medias-count>0</full-medias-count>
<published-at>2018-11-29T11:29:27+01:00</published-at>
<comments-count>0</comments-count>
<parent-uuid>b30fc050-2f14-11e2-a575-002219dda2c0</parent-uuid>
<gallery-display-style-uuid>5de339ba-04c5-11e1-a781-002219dda2c0</gallery-display-style-uuid>
<cover-media-uuid nil="true"/>
</gallery>
<location>/websites/xxxx_photodeck_com/galleries/f95eee28-f2ff-45fd-9d91-8c534894bd9b.xml</location>
<user-medias-gallery-proxy-uuid>5e9a601b-9a8c-4427-8aa9-0a0f1a48f24b</user-medias-gallery-proxy-uuid>
<message>Gallery successfully created. Your website will be updated within a few minutes.</message>
<request>POST /websites/xxxx_photodeck_com/galleries.xml</request>
</reply>

Media collections creation (POST /medias_groups.xml)

Same as media upload: UUID of newly created collections will move to <medias-collection>/<uuid> (or <medias-smart-collection>/<uuid> for smart collections). Make sure that your current code can accept this additional structure in the API response.

Details of newly created collection will also be directly provided in the additional collection structure, so that a subsequent API call to retrieve details of the newly created collection is not required anymore. Example:

<?xml version="1.0" encoding="UTF-8"?>
<reply>
<medias-collection-uuid>9c7b11e9-cdbf-4167-9e30-8289e90a8435</medias-collection-uuid>
<medias-collection>
<uuid>9c7b11e9-cdbf-4167-9e30-8289e90a8435</uuid>
<name>New collection</name>
<medias-count>0</medias-count>
</medias-collection>
<location>/medias_groups/9c7b11e9-cdbf-4167-9e30-8289e90a8435.xml</location>
<message>Successfully created.</message>
<request>POST /medias_groups.xml</request>
</reply>

Listing of all galleries on a website (GET /websites/.../galleries.xml)

Pagination will now be required to retrieve the list of all galleries.

Unpaginated requests will now be limited to the 5000 first galleries (instead of being unlimited as it is now). This limit will be further lowered to 500 in the future.

You may request up to 500 galleries per API call: set the page and per_page parameters accordingly. Total number of pages will be returned in <total-pages>. Stop iterating when reaching that last page, or when the <galleries> array is empty or contains less galleries than the per_page parameter.

Example, first page of galleries (GET /websites/xxxx_photodeck_com/galleries.xml?page=1&per_page=50):

<?xml version="1.0" encoding="UTF-8"?>
<reply>
<galleries type="array">
<gallery>
<uuid>b46fe3a8-38e0-11df-bd06-002219dda2c0</uuid>
</gallery>
[....]
</galleries>
<total-pages type="integer">12</total-pages>
<request>GET /websites/xxxx_photodeck_com/galleries.xml</request>
<query-string>page=1&per_page=50</query-string>
</reply>

Do not forget to rate limit API calls (not more than 1 request per second)!