swh.web.api.views.origin module

swh.web.api.views.origin.api_origins(request)[source]
GET /api/1/origins/

Get list of archived software origins.

Warning

This endpoint used to provide an origin_from query parameter, and guarantee an order on results. This is no longer true, and only the Link header should be used for paginating through results.

Query Parameters
  • origin_count (int) – The maximum number of origins to return (default to 100, can not exceed 10000)

Response JSON Array of Objects
  • origin_visits_url (string) – link to in order to get information about the visits for that origin

  • url (string) – the origin canonical url

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
  • Content-Type – this depends on Accept header of request

  • Link – indicates that a subsequent result page is available and contains the url pointing to it

Status Codes

Example:

https://archive.softwareheritage.org/api/1/origins?origin_count=500
swh.web.api.views.origin.api_origin(request, origin_url)[source]
GET /api/1/origin/(origin_url)/get/

Get information about a software origin.

Parameters
  • origin_url (string) – the origin url

Response JSON Object
  • origin_visits_url (string) – link to in order to get information about the visits for that origin

  • url (string) – the origin canonical url

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
Status Codes

Example:

https://archive.softwareheritage.org/api/1/origin/https://github.com/python/cpython/get/
GET /api/1/origin/search/(url_pattern)/

Search for software origins whose urls contain a provided string pattern or match a provided regular expression. The search is performed in a case insensitive way.

Warning

This endpoint used to provide an offset query parameter, and guarantee an order on results. This is no longer true, and only the Link header should be used for paginating through results.

Parameters
  • url_pattern (string) – a string pattern

Query Parameters
  • limit (int) – the maximum number of found origins to return (bounded to 1000)

  • with_visit (boolean) – if true, only return origins with at least one visit by Software heritage

Response JSON Array of Objects
  • origin_visits_url (string) – link to in order to get information about the visits for that origin

  • url (string) – the origin canonical url

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
  • Content-Type – this depends on Accept header of request

  • Link – indicates that a subsequent result page is available and contains the url pointing to it

Status Codes

Example:

https://archive.softwareheritage.org/api/1/origin/search/python/?limit=2
GET /api/1/origin/metadata-search/

Search for software origins whose metadata (expressed as a JSON-LD/CodeMeta dictionary) match the provided criteria. For now, only full-text search on this dictionary is supported.

Query Parameters
  • fulltext (str) – a string that will be matched against origin metadata; results are ranked and ordered starting with the best ones.

  • limit (int) – the maximum number of found origins to return (bounded to 100)

Response JSON Array of Objects
  • origin_visits_url (string) – link to in order to get information about the visits for that origin

  • url (string) – the origin canonical url

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
Status Codes

Example:

https://archive.softwareheritage.org/api/1/origin/metadata-search/?limit=2&fulltext=Jane%20Doe
swh.web.api.views.origin.api_origin_visits(request, origin_url)[source]
GET /api/1/origin/(origin_url)/visits/

Get information about all visits of a software origin. Visits are returned sorted in descending order according to their date.

Parameters
  • origin_url (str) – a software origin URL

Query Parameters
  • per_page (int) – specify the number of visits to list, for pagination purposes

  • last_visit (int) – visit to start listing from, for pagination purposes

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
  • Content-Type – this depends on Accept header of request

  • Link – indicates that a subsequent result page is available and contains the url pointing to it

Response JSON Array of Objects
  • date (string) – ISO representation of the visit date (in UTC)

  • origin (str) – the origin canonical url

  • origin_url (string) – link to get information about the origin

  • status (string) – status of the visit (either full, partial or ongoing)

  • visit (number) – the unique identifier of the visit

  • id (number) – the unique identifier of the origin

  • origin_visit_url (string) – link to GET /api/1/origin/(origin_url)/visit/(visit_id)/ in order to get information about the visit

>jsonarrarr string snapshot

the snapshot identifier of the visit (may be null if status is not full).

>jsonarrarr string snapshot_url

link to GET /api/1/snapshot/(snapshot_id)/ in order to get information about the snapshot of the visit (may be null if status is not full).

Status Codes

Example:

https://archive.softwareheritage.org/api/1/origin/https://github.com/hylang/hy/visits/
swh.web.api.views.origin.api_origin_visit_latest(request, origin_url=None)[source]
GET /api/1/origin/(origin_url)/visit/latest/

Get information about the latest visit of a software origin.

Parameters
  • origin_url (str) – a software origin URL

Query Parameters
  • require_snapshot (boolean) – if true, only return a visit with a snapshot

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
Response JSON Object
  • date (string) – ISO representation of the visit date (in UTC)

  • origin (str) – the origin canonical url

  • origin_url (string) – link to get information about the origin

  • status (string) – status of the visit (either full, partial or ongoing)

  • visit (number) – the unique identifier of the visit

Response JSON Array of Objects
  • snapshot (string) – the snapshot identifier of the visit (may be null if status is not full).

  • snapshot_url (string) – link to GET /api/1/snapshot/(snapshot_id)/ in order to get information about the snapshot of the visit (may be null if status is not full).

Status Codes
  • 200 OK – no error

  • 404 Not Found – requested origin or visit can not be found in the archive

Example:

https://archive.softwareheritage.org/api/1/origin/https://github.com/hylang/hy/visit/latest/
swh.web.api.views.origin.api_origin_visit(request, visit_id, origin_url)[source]
GET /api/1/origin/(origin_url)/visit/(visit_id)/

Get information about a specific visit of a software origin.

Parameters
  • origin_url (str) – a software origin URL

  • visit_id (int) – a visit identifier

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
Response JSON Object
  • date (string) – ISO representation of the visit date (in UTC)

  • origin (str) – the origin canonical url

  • origin_url (string) – link to get information about the origin

  • status (string) – status of the visit (either full, partial or ongoing)

  • visit (number) – the unique identifier of the visit

Response JSON Array of Objects
  • snapshot (string) – the snapshot identifier of the visit (may be null if status is not full).

  • snapshot_url (string) – link to GET /api/1/snapshot/(snapshot_id)/ in order to get information about the snapshot of the visit (may be null if status is not full).

Status Codes
  • 200 OK – no error

  • 404 Not Found – requested origin or visit can not be found in the archive

Example:

https://archive.softwareheritage.org/api/1/origin/https://github.com/hylang/hy/visit/1/
swh.web.api.views.origin.api_origin_intrinsic_metadata(request, origin_url)[source]
GET /api/1/origin/(origin_url)/intrinsic-metadata

Get intrinsic metadata of a software origin (as a JSON-LD/CodeMeta dictionary).

Parameters
  • origin_url (string) – the origin url

Response JSON Object
  • ??? (string) – intrinsic metadata field of the origin

Request Headers
  • Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers
Status Codes

Example:

https://archive.softwareheritage.org/api/1/origin/https://github.com/python/cpython/intrinsic-metadata