Mirrors API

From Mandriva Community Wiki

Jump to: navigation, search

Contents


[edit] Existing API

Starting with Mandriva Linux 2007.0, rpmdrake download a file located on the http://api.mandriva.com/ server. The exact URL is build as:

/mirrors/{type}.{version}.{branch}.{arch}.list

The product type, version, branch and architecture are derived from the product id attributes, and must be lowercased.

Note that for compatibility reasons with 2007.x versions out there, the following file format is available as well:

/mirrors/{type}.{version}.{arch}.list linking to /mirrors/{type}.{version}.final.{arch}.list

What is returned is a list, each line describing a valid mirror. Take http://api.mandriva.com/mirrors/basic.2007.1.i586.list for instance. The first line reads:

zone=GB,country=United Kingdom,city=Coventry,version=cooker,arch=i586,type=distrib,url=ftp://anorien.csc.warwick.ac.uk/Mandriva/devel/cooker/i586

Attributes of each line are

! attribute name possible values
zone
country
city
version
arch
type distrib, updates
url

[edit] Obsolete API

Old distribution releases (2006.0 and before) bundled rpmdrake used to download the http://www.mandrivalinux.com/mirrorsfull.list mirrors list file. It is an deprecated method.

[edit] Spec for a more versatile mirror API

This is a draft. Please complete it or discuss it.

This API is supposed to allow:

  • mirrors to be manually/automatically declared, for somewhat arbitrary content
  • people/programs to check for existing mirrors information

Note that this API goal is not to describe medias, distributions, and so on. Just to say "this mirror has an accurate copy of this item you asked me for".

The return XML format is not defined yet. Especially, one should investigate whether the GData protocol could be used there (not sure it could be useful; advice?).

TODO: detail HTTP return codes.

[edit] Methods

[edit] Add/declare a mirror

A mirror is just a host accessible through a specific protocol, nothing more. To declare that a mirror is mirroring something, use "set status" method below.

HTTP POST on http://api/mirror

name type sample value what is it? mandatory?
api_key string blabla mirror owner api key yes
host string dl.mandriva.com mirror host name yes
scheme string https mirror host access scheme yes
basepath string /rpm default mirror path no; defaults to /
country string FR country where the mirror is no; defaults to GeoIP

May return:

  • an error document (see bottom of page),
  • a success document:

<?xml version="1.0" encoding="utf-8"?>
<mirror>
<id>12</id>
<action>added</action>
</mirror>

[edit] Remove a mirror

This method removes the given mirror, and all references related to it (objects mirrored).

HTTP DELETE on http://api/mirror

name type sample value what is it? mandatory?
id integer 12 mirror id yes
key string blabla mirror owner api key yes

Returns an error document, or a success document:

<mirror>
<id>12</id>
<action>removed</action>
</mirror>

[edit] Set a mirror status

This method provides the possibility to a mirror owner to declare what she mirrors. Calling this does not mean that the mirror is in sync; the mirror API backend will be in charge of this (making sure things are in sync outside).

Note: it is obvious mirror owners won't care about using such methods, but if we provide them with a simple interface to declare their mirrors, easier/faster than an email. Availability of these methods (add/remove/set status) does not mean mirrors should not be handled by someone anyway.

Identifier of a release can be used to query an other API to know exactly what this release is. Identifier of a media is significant against its release identifier.

HTTP PUT on http://api/mirror

name type sample value what is it? mandatory?
id integer 12 mirror id yes
POST: key string blabla mirror owner api key yes
POST: for string release,media,file kind of "object" mirrored yes
POST: id string identifier of the "object" mirror yes
POST: path string where can it be found on the mirror no, defaults to =/=
POST: status boolean 0 whether it is mirroring or not no, defaults to 1

Note: setting status to 0 means the host does not mirror anymore the given object. That is:

  • http://api/mirror?id=12&key=A&for=iso&master=http://ftp.example.org/pub/MyIsoFile.iso&id=MyIsoFile.iso&path=/public/isos says that MyIsoFile.iso is mirrored by the host identified with 12;
  • http://api/mirror?key=A&for=iso&id=MyIsoFile.iso&path=/public/isos&status=0 says the ISO is no more mirrored.

We don't need to provide the service with a "master copy" location of the object we are mirroring. Because the object mirrored MUST be a known one, so it MUST have already an identifier (being a release, a media of a release, or an ISO), and an other service is storing this information (mapping the identifier to the full description of the object, including its master copy location).

[edit] Get a mirror for a release, for a media of a release, for an arbitrary item

This method provides an easy way to retrieve mirrors for specific objects (a distribution, a very media of a distribution, an ISO, a file.

Note that returned info is just the full path to the mirror:

  • for an ISO or a file, append the returned path to the file name, and GET it;
  • for a distribution mirror, append media/media_info/media.cfg to the full path, and let urpmi handle the media.cfg file to add medias;
  • for a media mirror, append media_info/hdlist.cz to get the hdlist for the media (media_info/descriptions.cz for update medias) to get the hdlist; this, of course, means that all medias MUST have a consistent structure.

HTTP GET on http://api/mirror

name type sample value what is it? mandatory?
for string release,media,file type of object yes
id see Release Spec object id yes
username string no
password string no

A HTTP GET on http://api/mirror?for=media&id=vendor=Mandriva,distribution=Mandriva%40Linux,type=Basic,version=2006.0,branch=Official,arch=x86_64,media=main may return:

<?xml version="1.0" encoding="utf-8"?>
<mirrors>
<mirror>
<url>ftp://ftp.free.fr/pub/Distributions_Linux/MandrivaLinux/official/2006.0/x86_64/media/main
</url>
</mirror>
...
</mirrors>

TODO detailed answer with details about mirror.

[edit] Get all mirrors belonging to self

This method provides the possibility, for someone, to view all mirrors (and items mirrored on it) registered, and their sync status.

HTTP GET on http://api/mirror

name type sample value what is it? mandatory?
key string blabla mirror owner key yes

[edit] Backend

[edit] Data model

(just a draft, no definitive)
Image:mirrorAPI.png

[edit] Tasks

Regularly check for mirrors if these are up to date.?

TBD

Retrieved from "http://wiki.mandriva.com/en/Mirrors_API"
Personal tools