Web/API/Specs

From Mandriva Community Wiki

Jump to: navigation, search
Mandriva Web APIs policy

This document specifies general rules for Mandriva web APIs.

Contents


Note: each API is explained here with a base URL http://api.mandriva.com/{api-name}/ . Of course, it may be that we need to dispatch APIs on different base servers (like http://a.mandriva.com/api/ for products, etc.). This will be decided later.

[edit] Versioning

Each API should expose an API version (http://api.mandriva.com/{api-name}/{api-version}/). Each version may support revisions, but those need to be backward compatible. In case of a version upgrade, N-1 API version MUST be supported, N-i (i > 1) MAY be supported.

[edit] Data encoding

Each API MUST suppose input data to be UTF-8 encoded, and MUST produce UTF-8 encoded data.

[edit] Protocols

Each API SHOULD share the same base protocol. API protocol(s) is not yet fully decided.

A REST API MUST provide at least answer in the following return formats:

It MAY provide other return formats as well (serialized PHP, RDF, RSS, CSV, other), depending on its purpose. If service consumer wants a particular format, it MUST say so using a format GET parameter (http://api/method?format=rdf).

For POST requests, input format for REST APIs MUST be valid XML, UTF-8 encoded.

Discussion:

  • SOAP is nice, somehow easier/faster to implement than REST, but heavy, and not compatible with a plain output;
  • both (REST/SOAP) may be difficult to handle (need to find a way to unify the dispatcher code);
  • a unified Mandriva XML schema should be defined, for all APIs, then. Or several schemas, per API/namespace.

Condider GData protocol (http://code.google.com/apis/gdata/protocol.html ).

[edit] Documentation

Each API MUST have a doc publishing its methods, input and ouput data formats.

[edit] Identifying resources (redirections)

For each API, some items MAY have alias permanent identifiers for the GET/HEAD methods (which MUST then redirect to the right one with a HTTP 301 return code), in the form http://api.mandriva.com/{api-name}/{api-version}/{simple-unique-id}. Note that if you deprecate an identifier, you MUST use this mechanism so the client knows where to look the right resource. All other HTTP methods (PUT, POST, DELETE) MUST use the permanent identifier.

Permanent identifiers (or their aliases) SHOULD be used by any Mandriva system to refer to the actual object. That is, for instance:

  • when Store refers to a given Mandriva product (say, Discovery 2006.0 for x86_64), it should refer to it, on the backend, with the product API identifier;
  • when Expert refers to a given support type, it should use product, support APIs identifiers on the backend side;
  • and so on.

This has to be stressed out again: the very same identifiers should be used over all online services, and if possible, within the distribution system as well.

[edit] API user key

Each API MAY require an API key to be used. The advantage of using such a key is to track resources usage. If used, a key MUST be personal and unique. Any service abuse SHOULD trigger the key revocation.

On the backend side, the key MUST be attached to the Mandriva user account.

[edit] (a)synchronism

For first versions, API are supposed to be synchronous (that is, you request something, you get an answer at once). A further spec will define whether/how some may be asynchronous (you request something and continue your job; the server will answer you later at an convened place).

Retrieved from "http://wiki.mandriva.com/en/Web/API/Specs"
Personal tools