Username
Password

Symfony Plugins API (v 1.0 - alpha)

Introduction

The symfony plugins API is a REST-style API for the symfony plugins available on the official symfony website. It is accessible through plain HTTP.

The read part of the API is very simple and returns either single records or collection of records as XML documents (all calls must be made with the GET HTTP method).

As for the write part of the API, it does not replace (yet) the Web console, but allows the developer to change the user plugins usage.

The API is in a preview mode. It means that everything is alpha and subject to change.

The API is only available for non-commercial use.

Base URL

All URLs start with http://www.symfony-project.org/plugins/api/1.0/.

In the following sections of this document, all examples use the curl utility. You can of course use whatever tool you want, and even test the API with a standard browser like Firefox.

Authentication

All API calls need to be authenticated with the HTTP Basic authentication scheme.

You can use the credentials of your symfony account:

$ curl -u username:password http://www.symfony-project.org/plugins/api/1.0/...

Or you can use the API key (you can find it on your profile page) as the username and x as the password:

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/...

It is almost always better to use the api_key authentication method, especially if you need to give access to your account to a third-party application as the API key just gives the application access to the API, and not to other parts of your symfony account.

The API key is regenerated each time you change your password.

Encoding

All responses from the API are UTF-8 encoded.

Data Type

The API uses three different data types in the XML documents it returns:

Dates: formatted as ATOM dates (2009-05-07T08:30:59+02:00);
Booleans: either 1 or 0;
Strings.

Links

The API returns linked elements to ease auto-discovering of features by following links found in link attributes:

<plugins>
  <plugin id="sfNadaPlugin" link="http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin.xml">
 
  ...
</plugins>

In the above snippet, the link attribute (http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin.xml) of the plugin tag is the URL to use to get the sfNadaPlugin resource.

You are more than encouraged to use these links, instead of hardcoding the URL patterns in your code. It will ease future migrations if we decide to change the URL patterns. To get top-level resource URLs, use the root.xml API call described below.

Write Methods

When using write methods, you must use the appropriate HTTP methods as indicated in the documentation (POST, PUT, or DELETE).

To acknowledge a change, the API returns a simple XML document:

<?xml version="1.0" encoding="UTF-8" ?>
 
<response status="1" />

If you use curl, use the -X flag to change the default GET method:

$ curl -X POST -u api_key:x http://www.symfony-project.org/plugins/api/1.0/...

Errors

If a request fails, an error is returned as the HTTP status code, and more information is available in the body, as an XML document.

If you try to get information for a resource that does not exist, the API returns a 404 error:

<?xml version="1.0" encoding="utf-8" ?>
 
<error code="404" message="Not Found" />

If the credentials are wrong, the API sends a 401 status code:

<?xml version="1.0" encoding="utf-8" ?>
 
<error code="401" message="Unauthorized" />

Rate Limit

At launch, all accounts are restricted to a maximum of 50 requests per hour. This limit should be more than enough for most usages.

One way to avoid the rate limit is to cache the API responses, as they change quite infrequently.

If you often hit the limit and think you have a legitimate usage of the API, send an email to fabien.potencier [at] symfony-project.org explaining your case.

Root

The only stable URL of the API is the root.xml URL:

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/root.xml

GET /root.xml returns all available top-level resource URLs:

<resources>
  <resource id="categories" link="http://www.symfony-project.org/plugins/api/1.0/categories.xml" />
  <resource id="developers" link="http://www.symfony-project.org/plugins/api/1.0/developers.xml" />
  <resource id="plugins" link="http://www.symfony-project.org/plugins/api/1.0/plugins.xml" />
</resources>

List of Plugins

All plugins

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins.xml

GET /plugins.xml returns all plugins:

<plugins>
  <plugin id="sfNadaPlugin" link="http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin.xml">
    <description>Description in HTML</description>
    <image>http://www.symfony-project.org/images/plugin_default.png</image>
    <date>2009-05-07T08:30:59+02:00</date>
    <users>0</users>
    <scm>http://svn.symfony-project.com/plugins/sfNadaPlugin</scm>
    <homepage>http://www.nadaplugin.org/</homepage>
    <ticketing>http://trac.nadaplugin.org/</ticketing>
  </plugin>
 
  ...
</plugins>

You can get only the more recent plugins by passing since as a query string parameter:

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins.xml?since=1241695171

Plugins for a Category

When you get the information for a category (see the Category section), the API returns the list of plugins associated with the category.

Plugins for a Developer

When you get the information for a developer (see the Developer section), the API returns the list of plugins associated with the developer.

Plugin

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin.xml

GET /plugins/sfNadaPlugin.xml returns information about a plugin:

<plugin>
  <releases>
    <release version="1.0.0" link="http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin/releases/1.0.0.xml">
      <stability>stable</stability>
      <summary>The popular Nada plugin.</summary>
      <channel>plugins.symfony-project.org</channel>
      <license>MIT license</license>
      <date>2009-05-07T08:30:59+02:00</date>
      <symfony>
        <min>1.2.0</min>
        <max>1.3.0</max>
      </symfony>
    </release>
 
    ...
  </releases>
</plugin>

Plugin Release

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin/releases/1.0.0.xml

GET /plugins/sfNadaPlugin/releases/1.0.0.xml returns information about a plugin:

<release>
  <stability>stable</stability>
  <summary>The popular Nada plugin.</summary>
  <description>Description in HTML</description>
  <channel>plugins.symfony-project.org</channel>
  <license>MIT license</license>
  <date>2009-05-07T08:30:59+02:00</date>
  <symfony>
    <min>1.2.0</min>
    <max>1.3.0</max>
  </symfony>
  <readme>README in HTML</readme>
  <changelog>CHANGELOG in HTML</changelog>
  <license-text>Licence text</license-text>
  <developers>
    <developer id="fabien-potencier" link="http://www.symfony-project.org/plugins/api/1.0/developers/fabien-potencier.xml">
      <role>leader</role>
    </developer>
  </developers>
  <dependencies>
    <dependency id="sfNada2Plugin" required="1" link="http://www.symfony-project.org/plugins/api/1.0/plugins/sfNada2Plugin.xml">
      <version>
        <min>3.0.0</min>
        <max>4.0.0</max>
      </version>
    </dependency>
  </dependencies>
</release>

Developers

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/developers.xml

GET /developers.xml returns all developers:

<developers>
  <developer id="fabien-potencier" link="http://www.symfony-project.org/plugins/api/1.0/developers/fabien-potencier.xml">
    <name>Fabien Potencier</name>
  </developer>
  ...
</developers>

Developer

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/developers/fabien-potencier.xml

GET /developers/fabien-potencier.xml returns information about a developer:

<developer>
  <name>Fabien Potencier</name>
  <plugins>
    <plugin>
      ...
    </plugin>
  </plugins>
</developer>

Profile

You can get more information about the current user by accessing its profile:

$ curl -u api_key:x http://www.symfony-project.org/plugins/api/1.0/profile.xml

GET /profile.xml returns information about the current user:

<profile>
  <username>fabien</username>
  <email>fabien@example.com</email>
  <stack>
    <plugin>
      ...
    </plugin>
  </stack>
</profile>

Notice that you get the stack of plugins as flagged by the user.

User Plugin Stack

Get the user stack

You can get the user plugins stack by getting the user profile (see the Profile section above).

Add a plugin to the user stack

You can add a plugin to the user plugin stack:

$ curl -X PUT -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin/users.xml

PUT /plugins/sfNadaPlugin/users.xml returns a 200 status code if the change has been made. If the plugin is already in the user stack, the call is simply ignored, and a 200 status code is also returned.

Remove a plugin from the user stack

Similarly, you can also remove a plugin from the user stack by using the DELETE HTTP method:

$ curl -X DELETE -u api_key:x http://www.symfony-project.org/plugins/api/1.0/plugins/sfNadaPlugin/users.xml

As before, DELETE /plugins/sfNadaPlugin/users.xml returns a 200 status code if the change has been made or if the plugin is not in the user stack.

Plugins API

Signin

Tools

Stats

Symfony Plugins API (v 1.0 - alpha)

Introduction

Base URL

Authentication

Encoding

Data Type

Links

Write Methods

Errors

Rate Limit

Root

List of Plugins

All plugins

Plugins for a Category

Plugins for a Developer

Plugin

Plugin Release

Developers

Developer

Profile

Categories

Category

User Plugin Stack

Get the user stack

Add a plugin to the user stack

Remove a plugin from the user stack

	About Installation Documentation Plugins Community Blog Development

Plugins API