Old API phaseout, new API changes and best practices for the Cache

Over the recent months we incorporated a lot of feedback into the development of our API. Ultimatly we want to make it as easy and straight forward as possible to build Apps and services on top of our infrastructure.

Phaseout of the old direct download API

To gain flexibility we redeveloped our API and consolidated it into one framework. The new API and its functions are published at swaggerhub.
Important: We will phase out the old method on December 1st 2018. It will no longer work after that date.

Authentication of your app

We have two authentication methods. We greatly prefer oAuth as it creates a seamless experience for the users login. You can register your app here to use the oAuth login.

API Best Practices for Cloud, Transfers and Downloads

The Premiumize.me Api allows you to do almost anything via API that you already see on the website. We added our API to swagger so you can try out the calls in real time.

1. Check the cache
   This API call does not use up any fair use quota. It will give you a status if we have the file or not. If it is a hit, the file will be available instantly with 100% availability. You can lookup the cache by link, filehash or magnet.
   Important: There are two list of services. One contains the domains which can be found in the cache, the other one contains the list for which download links can be generated. The list for the cache is bigger, because for some domains we have the links in the cache, but cannot generate new links in real time.
2. Create a download job if you want to add content to the cloud
   You will need to wait until the job is finished. If it is a cached item, expect it to finish instantly. If we need to grab the content remotely, then it will take a bit. Especially usenet’s nzb downloads take a longer time as the job needs quite a bit of postprocessing. Use the job information function to look up the status of the job. Jobs use fair use points on creation.
3. Make use of transcoded files
   Some video files in the Premiumize.me cloud get postprocessed to a reasonable bitrate and video format so that native browser playback is possible. In all cases we keep the original file. It depends on your app if you want to give the user the option of a stream-optimised transcoded file or if you only display the original file. In any case should the user be informed if you do not hand him the actual original file he requested.
4. NEW: Use the direct download link function if needed
   This is the most popular and straight forward function when it comes to download managers or simple download tools. Generated direct download links cost the user fair use points on successful generation of the link. The fair use point cost depend on what kind of service it is so it makes sense to prioritise requesting files from sources that are cheap; or for file content that is cached as it will have a guaranteed availability.
   The direct-download function can request any supported and any cached links, magnet and usenet. If the cached link has multiple files, you will receive multiple links and the folder structure.
   In extreme cases supported hosts vary by day. Make sure to check with the list function that the service is supposed to work for direct downloads and what fair use factor it has. This way you can prioritise cheaper hosts.
5. Clean up the users cloud
   Currently, used storage merely reserves fair use points. The points are credited back if the user deletes the file. Give hints in your addon in case it is confusing. Note: You can get links of already cached torrents with the direct download link function of the above point.

An eloquent example

You want to grab content from the internet and you have the choice between 10 different links. You submit all 10 links to the free cache lookup function. If you are lucky, Premiumize lets you know that we already cached the content behind 3 of the 10 links. You show your users these results and give him the option to either a) collect the content by transferring into his cloud or b) download/stream immediately by creating a direct download link. Since it is a cached link, the user only has to pay 1 point per gigabyte and he won’t run into any limits fast. In case there is no cached hit, you can request the content from the most stable and cheap service. If a magnet is cached and the user does not want to save it to his cloud, you can get premium links with the direct download function.