API Documentation

This is Software Heritage’s SWORD 2.0 Server implementation.

S.W.O.R.D (Simple Web-Service Offering Repository Deposit) is an interoperability standard for digital file deposit.

This implementation will permit interaction between a client (a repository) and a server (SWH repository) to push deposits of software source code archives with associated metadata.

Note:

• In the following document, we will use the archive or software source code archive interchangeably.

• The supported archive formats are:

  • zip: common zip archive (no multi-disk zip files).

  • tar: tar archive without compression or optionally any of the following compression algorithm gzip (.tar.gz, .tgz), bzip2 (.tar.bz2) , or lzma (.tar.lzma)

Collection

SWORD defines a collection concept. In SWH’s case, this collection refers to a group of deposits. A deposit is some form of software source code archive(s) associated with metadata. By default the client’s collection will have the client’s name.

Limitations

• upload limitation of 100Mib

• no mediation

API overview

API access is over HTTPS.

The API is protected through basic authentication.

Endpoints

The API endpoints are rooted at https://deposit.softwareheritage.org/1/.

Data is sent and received as XML (as specified in the SWORD 2.0 specification).

• Service document
• Create deposit
• Update content
• Update metadata
• Retrieve status
  • Rejected deposit
• Display content

Possible errors:

• common errors:

  • 401 Unauthorized:if a client does not provide credential or provide wrong ones

  • 403 Forbidden a client tries access to a collection it does not own

  • 404 Not Found if a client tries access to an unknown collection

  • 404 Not Found if a client tries access to an unknown deposit

  • 415 Unsupported Media Type if a wrong media type is provided to the endpoint

• archive/binary deposit:

  • 403 Forbidden the length of the archive exceeds the max size configured

  • 412 Precondition Failed the length or hash provided mismatch the reality of the archive.

  • 415 Unsupported Media Type if a wrong media type is provided

• multipart deposit:

  • 412 Precondition Failed the md5 hash provided mismatch the reality of the archive

  • 415 Unsupported Media Type if a wrong media type is provided

• Atom entry deposit:

  • 400 Bad Request if the request’s body is empty (for creation only)

Sources

• SWORD v2 specification

• arxiv documentation

• Dataverse example

• SWORD used on HAL

• xml examples for CCSD