swh.web.save_code_now.api_views module#

class swh.web.save_code_now.api_views.OriginSaveQuerySerializer(*args, **kwargs)[source]#

Bases: Serializer

Origin citation query parameters serializer.

When a field is instantiated, we store the arguments that were used, so that we can present a helpful representation of the object.

validate(data: dict) → dict[source]#

Validate visit_type and origin_url.

visit_type is required if origin_url is defined and vice versa.

Parameters:

data – query parameters

Raises:

serializers.ValidationError – invalid parameters

Returns:

query parameters

swh.web.save_code_now.api_views.api_save_origin(request: Request, visit_type: str | None = None, origin_url: str | None = None, request_id: int = 0, validated_query_params: Dict[str, str] | None = None)[source]#
GET /api/1/origin/save/(visit_type)/url/(origin_url)/#
POST /api/1/origin/save/(visit_type)/url/(origin_url)/#
GET /api/1/origin/save/?visit_type=(visit_type)&origin_url=(origin_url)#
POST /api/1/origin/save/?visit_type=(visit_type)&origin_url=(origin_url)#
GET /api/1/origin/save/(request_id)/#

Request the saving of a software origin into the archive or check the status of previously created save requests.

That endpoint enables to create a saving task for a software origin through a POST request.

Depending of the provided origin url, the save request can either be:

  • immediately accepted, for well known code hosting providers like for instance GitHub or GitLab

  • rejected, in case the url is blacklisted by Software Heritage

  • put in pending state until a manual check is done in order to determine if it can be loaded or not

Once a saving request has been accepted, its associated saving task status can then be checked through a GET request on the same url. Returned status can either be:

  • not created: no saving task has been created

  • pending: saving task has been created and will be scheduled for execution

  • scheduled: the task execution has been scheduled

  • running: the task is currently executed

  • succeeded: the saving task has been successfully executed

  • failed: the saving task has been executed but it failed

When issuing a POST request an object will be returned while a GET request will return an array of objects (as multiple save requests might have been submitted for the same origin).

It is also possible to get info about a specific save request by sending a GET request to the /api/1/origin/save/(request_id)/ endpoint.

Important

If the origin URL contains special characters like a white space or a question mark (meaning the URL has query parameters), you should rather pass the percent encoded origin_url and visit_type values through query parameters instead of URL arguments.

Parameters:

  • visit_type (string) – the type of visit to perform (currently the supported types are bzr, cvs, git, hg, svn, and tarball)

  • origin_url (string) – the url of the origin to save

  • request_id (number) – a save request identifier

Query Parameters:

  • visit_type (string) – the type of visit to perform (currently the supported types are bzr, cvs, git, hg, svn, and tarball)

  • origin_url (string) – the url of the origin to save

Request Headers:

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

Response Headers:
Response JSON Object:

  • id (number) – the save request identifier

  • request_url (string) – Web API URL to follow up on that request

  • origin_url (string) – the url of the origin to save

  • visit_type (string) – the type of visit to perform

  • save_request_date (string) – the date (in iso format) the save request was issued

  • save_request_status (string) – the status of the save request, either accepted, rejected or pending

  • save_task_status (string) – the status of the origin saving task, either not created, pending, scheduled, running, succeeded or failed

  • visit_date (string) – the date (in iso format) of the visit if a visit occurred, null otherwise.

  • visit_status (string) – the status of the visit, either full, partial, not_found or failed if a visit occurred, null otherwise.

  • note (string) – optional note giving details about the save request, for instance why it has been rejected

  • snapshot_swhid (string) – SWHID of snapshot associated to the visit (null if it is missing or unknown)

  • snapshot_url (string) – Web API URL to retrieve snapshot data

  • from_webhook (boolean) – indicates if the save request was created from a popular forge webhook receiver (see POST /api/1/origin/save/webhook/github/ for instance)

  • webhook_origin (string) – indicates which forge type sent the webhook, currently the supported types are:bitbucket, gitea, github, gitlab, and sourceforge

Status Codes: