Differences between revisions 3 and 4
Revision 3 as of 2013-11-16 11:10:31
Size: 2637
Editor: EnricoZini
Comment: Added the submission data format
Revision 4 as of 2013-11-16 11:17:36
Size: 3651
Editor: EnricoZini
Comment: Added information about posting data
Deletions are marked like this. Additions are marked like this.
Line 33: Line 33:
{{{type}}} is the string configured as a contribution type name in the source configuration on contributors.debian.org

{{{begin}}} is when one started contributing. If missing, the server will use the previously reported begin date. If no previous contribution has been seem, the server will use today's date.

{{{end}}} is the time of the last known contribution. If missing, the server will use today's date.

{{{url}}} is a URL pointing to a page that will list details of this kind of contributions for this person, if available. If missing, the server will just render the contribution details with plain text instead of a hyperlink.
 * {{{type}}} is the string configured as a contribution type name in the source configuration on contributors.debian.org
 * {{{begin}}} is when one started contributing. If missing, the server will use the previously reported begin date. If no previous contribution has been seem, the server will use today's date.
 * {{{end}}} is the time of the last known contribution. If missing, the server will use today's date.
 * {{{url}}} is a URL pointing to a page that will list details of this kind of contributions for this person, if available. If missing, the server will just render the contribution details with plain text instead of a hyperlink.
Line 79: Line 76:
== Posting a submission ==

Submission are sent via a {{{multipart/form-data}}} HTTP POST to {{{https://contributors.debian.org/contributors/post}}}

The JSON data is sent as a file field called 'data', so you will need an HTTP client capable of file uploads.

The other fields uploaded are:

 * {{{source}}} is the source name as configured in the site
 * {{{auth_token}}} is the authentication token configured in the site
 * {{{data_compression}}} (optional) is the data compression used for the JSON data (by default, no compression; {{{gzip}}} and {{{xz}}} are supported.

Example submission, with compression:
{{{
curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data_compression=gzip -F data=@filename.json.gz
}}}
Example plain submission:
{{{
curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data=@filename.json
}}}

Implementation notes

JSON structure of a submission

A submission is an array of Records:

Submission := [ Record ]

A Record is an object with the identity of the contributor and a list of contributions:

Record := { id: [ Identifier ], contributions: [ Contribution ] }

There can be more than one Identifier per Record, but there usually is only one. There can be one or more Contribution per Record.

An Identifier is an object identifying the contributor in one of many possible ways:

Identifier := { type: IdentifierType, id: string, desc: optional_string }

IdentifierType := "login"|"email"|"fpr"

Currently only debian.org or alioth login names, emails and OpenPGP key fingerprints are supported.

A Contribution is an object detailing one kind of contribution over time:

Contribution := { type: string, begin: optional_Date, end: optional_Date, url: optional_string }

Date := "yyyy-mm-dd"
  • type is the string configured as a contribution type name in the source configuration on contributors.debian.org

  • begin is when one started contributing. If missing, the server will use the previously reported begin date. If no previous contribution has been seem, the server will use today's date.

  • end is the time of the last known contribution. If missing, the server will use today's date.

  • url is a URL pointing to a page that will list details of this kind of contributions for this person, if available. If missing, the server will just render the contribution details with plain text instead of a hyperlink.

Examples

A minimal submission:

[
  { id: [ { type: "login", id: "enrico" } ],
    contributions: [
      { type: "talking" }
    ]
  },
  { id: [ { type: "login", id: "93sam" } ],
    contributions: [
      { type: "talking" }
    ]
  }
]

A more detailed submission:

[
  { id: [ { type: "login", id: "enrico" } ],
    contributions: [
      { type: "talking", begin: "2010-01-01", end: "2013-11-16",
        url: "http://talks.debian.org/enrico"
      }
    ]
  },
  { id: [ { type: "login", id: "93sam" } ],
    contributions: [
      { type: "talking", begin: "1990-05-01", end: "2013-11-16",
        url: "http://talks.debian.org/93sam"
      }
    ]
  }
]

Posting a submission

Submission are sent via a multipart/form-data HTTP POST to https://contributors.debian.org/contributors/post

The JSON data is sent as a file field called 'data', so you will need an HTTP client capable of file uploads.

The other fields uploaded are:

  • source is the source name as configured in the site

  • auth_token is the authentication token configured in the site

  • data_compression (optional) is the data compression used for the JSON data (by default, no compression; gzip and xz are supported.

Example submission, with compression:

curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data_compression=gzip -F data=@filename.json.gz

Example plain submission:

curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data=@filename.json

Data sources

  • web team (prototype): git.debian.org:~enrico/get-webteam-contributors

  • dak (prototype): nono.debian.org:~enrico/get-dak-contributors

Source code