Appendix D. API Reference in Red Hat Update Infrastructure

Note

All material cited here was taken from the Pulp 2.18 repository.

D.1. Repository APIs

D.1.1. Creation, deletion, and configuration

D.1.1.1. Create a repository

This call creates a new repository in Pulp and accepts optional parameters for importer and distributor configuration. More detailed description of these parameters can be found in the documentation of APIs to associate an importer or a distributor to an existing repository. If these parameters are not passed, the call will create the repository only in Pulp. The real functionality of a repository is not defined until importers and distributors are added. Repository IDs must be unique across all repositories in the server.

Method: POST

Path: /pulp/api/v2/repositories/

Permission: create

Request Body Contents

id
(string) unique identifier for the repository
display_name
(string) (optional) user-friendly name for the repository
description
(string) (optional) user-friendly text describing the repository’s contents
notes
(object) (optional) key-value pairs to programmatically tag the repository
importer_type_id
(string) (optional) type id of importer being associated with the repository
importer_config
(object) (optional) configuration the repository will use to drive the behavior of the importer. Note that proxy_password and basic_auth_password will be returned as * for security purposes.
distributors
(array) (optional) array of objects containing values of distributor_type_id, repo_plugin_config, auto_publish, and distributor_id

Response Codes

201
The repository was successfully created.
400
If one or more of the parameters is invalid
409
If there is already a repository with the given ID
500
If the importer or distributor raises an error during initialization

Return: database representation of the created repository

Sample Request: 

{
 "display_name": "Harness Repository: harness_repo_1",
 "id": "harness_repo_1",
 "importer_type_id": "harness_importer",
 "importer_config": {
   "num_units": "5",
   "write_files": "true"
 },
 "distributors": [{
               "distributor_id": "dist_1",
               "distributor_type_id": "harness_distributor",
               "distributor_config": {
               "publish_dir": "/tmp/harness-publish",
               "write_files": "true"
               },
               "auto_publish": false
       }],
}

Sample 201 Response Body: 

{
 "scratchpad": {},
 "display_name": "Harness Repository: harness_repo_1",
 "description": null,
 "_ns": "repos",
 "notes": {},
 "content_unit_counts": {},
 "_id": {
   "$oid": "52280416e5e71041ad000066"
 },
 "id": "harness_repo_1",
 "_href": "/pulp/api/v2/repositories/harness_repo_1/"
}

D.1.1.2. Update a repository

Much like create repository is simply related to the repository metadata (as compared to the associated importers/distributors), the update repository call is centered around updating only that metadata.

Method: PUT

Path: /pulp/api/v2/repositories/<repo_id>/

Permission: update

Request Body Contents: The body of the request is a JSON document with three possible root elements

delta
(object) (optional) object containing keys with values that should be updated on the repository
importer_config
(object) (optional) object containing keys with values that should be updated on the repository’s importer config
distributor_configs
(object) (optional) object containing keys that are distributor IDs, and values that are objects containing plugin specific keys/value pairs

Response Codes

200
If the update was executed and successful
202
If the update was executed but additional tasks were created to update nested distributor configurations
400
If one or more of the parameters is invalid
404
If there is no repository with the give ID

Return: A Call Report containing the database representation of the repository (after changes made by the update) and any tasks spawned to apply the consumer bindings for the repository. See Bind a Consumer to a Repository for details on the bindings tasks that will be generated.

Sample Request: 

{
 "delta": {
  "display_name" : "Updated"
 },
 "importer_config": {
  "demo_key": "demo_value"
 },
 "distributor_configs": {
  "demo_distributor": {
    "demo_key": "demo_value"
  }
 }
}

Sample result value: The result field of the Call Report contains the database representation of the repository. 

{
...
"result": {
   "display_name": "zoo",
   "description": "foo",
   "_ns": "repos",
   "notes": {
     "_repo-type": "rpm-repo"
   },
   "content_unit_counts": {
     "package_group": 2,
     "package_category": 1,
     "rpm": 32,
     "erratum": 4
   },
   "_id": {
     "$oid": "5328b2983738202945a3bb47"
   },
   "id": "zoo",
   "_href": "/pulp/api/v2/repositories/zoo/"

 },
 ...
}

D.1.1.3. Associate an importer to a repository

This call configures an importer for a previously created Pulp repository. Each repository maintains its own configuration for the importer, which is used to dictate how the importer will function when it synchronizes content. The possible configuration values are contingent on the type of importer being added; each importer type will support a different set of values relevant to how it functions.

Only one importer may be associated with a repository at a given time. If a repository already has an associated importer, the previous association is removed. The removal is performed before the new importer is initialized, thus there is the potential that if the new importer initialization fails the repository is left without an importer.

Adding an importer performs the following validation steps before confirming the addition:

  • The importer plugin is contacted and asked to validate the supplied configuration for the importer. If the importer indicates its configuration is invalid, the importer is not added to the repository.
  • The importer’s importer_added method is invoked to allow the importer to do any initialization required for that repository. If the plugin raises an exception during this call, the importer is not added to the repository.
  • The Pulp database is updated to store the importer’s configuration and the knowledge that the repository is associated with the importer.

The details of the added importer are returned from the call.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/importers/

Permission: create

Request Body Contents

importer_type_id
(string) - indicates the type of importer being associated with the repository; there must be an importer installed in the Pulp server with this ID
importer_config
(object) - configuration the repository will use to drive the behavior of the importer

Response Codes

202
If the association was queued to be performed
400
If one or more of the required parameters is missing, the importer type ID refers to a non-existent importer, or the importer indicates the supplied configuration is invalid
404
If there is no repository with the given ID
500
If the importer raises an error during initialization

Return: A Call Report containing the current state of the association task

Sample Request: 

{
 "importer_type_id": "harness_importer",
 "importer_config": {
   "num_units": "5",
   "write_files": "true"
 }
}

Sample result value for the Task Report: The result field of the Task Report will contain the database representation of the importer (not the full repository details, just the importer). 

{
 "scratchpad": null,
 "_ns": "repo_importers",
 "importer_type_id": "harness_importer",
 "last_sync": null,
 "repo_id": "harness_repo_1",
 "_id": "bab0f9d5-dfd1-45ef-bd1d-fd7ea8077d75",
 "config": {
   "num_units": "5",
   "write_files": "true"
 },
 "id": "harness_importer"
}

Tags: The task created will have the following tags: pulp:action:update_importer, pulp:repository:<repo_id>, pulp:repository_importer:<importer_type_id>

D.1.1.4. Associate a distributor with a repository

This call configures a distributor for a previously created Pulp repository. Each repository maintains its own configuration for the distributor, which is used to dictate how the distributor will function when it publishes content. The possible configuration values are contingent on the type of distributor being added; each distributor type supports a different set of values relevant to how it functions.

Note

There is an optional distributor configuration parameter that is usable on all distributor plugin types called force_full. If this parameter is set, every publish of the repo using this distributor is done from scratch. See Release Notes for more information.

Multiple distributors can be associated with a repository at a given time. There might be more than one distributor with the same type. The only restriction is that the distributor ID must be unique across all distributors for a given repository.

Adding a distributor performs the following validation steps before confirming the addition:

  • If provided, the distributor ID is checked for uniqueness in the context of the repository. If not provided, a unique ID is generated.
  • The distributor plugin is contacted and asked to validate the supplied configuration for the distributor. If the distributor indicates its configuration is invalid, the distributor is not added to the repository.
  • The distributor’s distributor_added method is invoked to allow the distributor to do any initialization required for that repository. If the plugin raises an exception during this call, the distributor is not added to the repository.
  • The Pulp database is updated to store the distributor’s configuration and the knowledge that the repository is associated with the distributor.

The details of the added distributor are returned from the call.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/distributors/

Permission: create

Request Body Contents

distributor_type_id
(string) Indicates the type of distributor being associated with the repository; there must be a distributor installed in the Pulp server with this ID.
distributor_config
(object) Plugin-specific configuration the repository uses to drive the behavior of the distributor
distributor_id
(string) (optional) If specified, this value refers to the distributor; if not specified, one is randomly assigned to the distributor.
auto_publish
(boolean) (optional) If true, this distributor automatically has its publish operation invoked after a successful repository sync. Defaults to false if unspecified.

Response Codes

201
If the distributor was successfully added
400
If one or more of the required parameters is missing, the distributor type ID refers to a non-existent distributor, or the distributor indicates the supplied configuration is invalid
404
If there is no repository with the given ID
500
If the distributor raises an error during initialization

Return: Database representation of the distributor (not the full repository details, just the distributor)

Sample Request: 

{
 "distributor_id": "dist_1",
 "distributor_type_id": "harness_distributor",
 "distributor_config": {
   "publish_dir": "/tmp/harness-publish",
   "write_files": "true"
 },
 "auto_publish": false
}

Sample 201 Response Body: 

{
 "scratchpad": null,
 "_ns": "repo_distributors",
 "last_publish": null,
 "auto_publish": false,
 "distributor_type_id": "harness_distributor",
 "repo_id": "harness_repo_1",
 "publish_in_progress": false,
 "_id": "cfdd6ab9-6dbe-4192-bde2-d00db768f268",
 "config": {
   "publish_dir": "/tmp/harness-publish",
   "write_files": "true"
 },
 "id": "dist_1"
}

D.1.1.5. Update an importer associated with a repository

Update the configuration for an importer that has already been associated with a repository.

Any importer configuration value that is not specified remains unchanged.

Note that the importer’s proxy_password and basic_auth_password fields return as * if they are populated. This is done for security purposes.

Method: PUT

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/

Permission: update

Request Body Contents

importer_config
(object) Object containing keys with values that should be updated on the importer

Response Codes

202
If the request was accepted by the server to update the importer when the repository is available
400
If request body parameters are invalid
404
If there is no repository or importer with the specified IDs

Return: A Call Report, which includes a spawned task that should be polled for a Task Report

Sample Request: 

{
 "importer_config": {
   "demo_key": "demo_value"
 }
}

Sample result value for the Task Report: The result field of the Task Report contains the database representation of the importer. This does not include the full repository details. 

[options="nowrap"]
{
  "scratchpad": null,
  "_ns": "repo_importers",
  "importer_type_id": "demo_importer",
  "last_sync": "2013-10-03T14:08:35Z",
  "scheduled_syncs": [],
  "repo_id": "demo_repo",
  "_id": {
    "$oid": "524db282dd01fb194283e53f"
  },
  "config": {
    "demo_key": "demo_value"
  },
  "id": "demo_importer"
}

Tags: The task created has the following tags: pulp:action:update_importer, pulp:repository:<repo_id>, pulp:repository_importer:<importer_id>

D.1.1.6. Disassociate an importer from a repository

Method: DELETE

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/

Permission: delete

Response Codes

202
If the request was accepted by the server to disassociate when the repository is available
404
If there is no repository or importer with the specified IDs

Return: A Call Report

Tags: The task created has the following tags: pulp:action:delete_importer, pulp:repository:<repo_id>, pulp:repository_importer:<importer_id>

D.1.1.7. Update a distributor associated with a repository

Update the configuration for a distributor associated with a repository. This performs the following actions:

  1. Updates the distributor on the server
  2. Rebinds any bound consumers

Any distributor configuration value that is not specified remains unchanged, and any value that is set to explicitly to None will be removed from the config.

The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required to complete Step 2. Updating a distributor causes each binding associated with that repository to be updated as well. See Bind a Consumer to a Repository for details.

Method: PUT

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/

Permission: update

Request Body Contents

distributor_config
(object) (optional) Object containing plugin specific keys with values that will update the distributor config
delta
(object) (optional) Object containing keys with values that will update the distributor object, currently only supports auto_publish

Response Codes

202
If the request was accepted by the server to update the distributor when the repository is available
404
If there is no repository or distributor with the specified IDs

Return: A Call Report

Sample Request: 

{
 "distributor_config": {
   "demo_key": "demo_value"
 },
 "delta": {
   "auto_publish": true
 }
}

Tags: The task created to update the distributor have the following tags: pulp:action:update_distributor, pulp:repository:<repo_id>, pulp:repository_distributor:<distributor_id>. Information about the binding tasks can be found at Bind a Consumer to a Repository.

D.1.1.8. Disassociate a distributor from a repository

Disassociating a distributor performs the following actions:

  1. Remove the association between the distributor and the repository.
  2. Unbind all bound consumers.

The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required complete step 2. The total number of spawned tasks depends on how many consumers are bound to the repository.

Method: DELETE

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/

Permission: delete

Response Codes

202
If the request was accepted by the server to disassociate when the repository is available
404
If there is no repository or distributor with the specified IDs
500
If the server raises an error during disassociation

Return: A Call Report

Tags: The task created to delete the distributor has the following tags: pulp:action:remove_distributor, pulp:repository:<repo_id>, pulp:repository_distributor:<distributor_id>

D.1.1.9. Delete a repository

When a repository is deleted, it is removed from the database and its local working directory is deleted. The content within the repository is not deleted. Deleting content is handled through the orphaned unit process.

Deleting a repository is performed in the following major steps:

  • Delete the repository.
  • Unbind all bound consumers.

The first step is represented by a Call Report. Upon completion of Step 1, the spawned_tasks field populates with links to any tasks required to complete Step 2. The total number of spawned tasks depends on how many consumers are bound to the repository.

Method: DELETE

Path: /pulp/api/v2/repositories/<repo_id>/

Permission: delete

Response Codes

202
If the request was accepted by the server to delete the repository
404
If the requested repository does not exist

Return: A Call Report

Tags: The task created to delete the repository has the following tags: pulp:action:delete,pulp:repository:<repo_id>

D.1.2. Retrieval

D.1.2.1. Retrieve a single repository

This call retrieves information on a single Pulp repository. The returned data includes general repository metadata, metadata describing any importers and distributors associated with it, and a count of how many content units have been stored locally for the repository.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/

Permission: read

Query Parameters

details
(boolean) (optional) Shortcut for including distributors, importers, and content unit counts
importers
(boolean) (optional) Include the importers attribute on each repository
distributors
(boolean) (optional) Include the “distributors” attribute on each repository

Response Codes

200
If the repository exists
404
If no repository exists with the given ID

Return: database representation of the matching repository

Sample 200 Response Body: 

{
 "display_name": "Harness Repository: harness_repo_1",
 "description": null,
 "distributors": [
   {
     "scratchpad": 1,
     "_ns": "repo_distributors",
     "last_publish": "2012-01-25T15:26:32Z",
     "auto_publish": false,
     "distributor_type_id": "harness_distributor",
     "repo_id": "harness_repo_1",
     "publish_in_progress": false,
     "_id": "addf9261-345e-4ce3-ad1e-436ba005287f",
     "config": {
       "publish_dir": "/tmp/harness-publish",
       "write_files": "true"
     },
     "id": "dist_1"
   }
 ],
 "notes": {},
 "scratchpad": {},
 "content_unit_counts": {},
 "last_unit_added": "2012-01-25T15:26:32Z",
 "last_unit_removed": "2012-01-25T15:26:32Z",
 "importers": [
   {
     "scratchpad": 1,
     "_ns": "repo_importers",
     "importer_type_id": "harness_importer",
     "last_sync": "2012-01-25T15:26:32Z",
     "repo_id": "harness_repo_1",
     "sync_in_progress": false,
     "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e",
     "config": {
       "num_units": "5",
       "write_files": "true"
     },
     "id": "harness_importer"
   }
 ],
 "id": "harness_repo_1",
 "total_repository_units": 5,
 "locally_stored_units": 3
}

D.1.2.2. Retrieve all repositories

This call returns information on all repositories in the Pulp server. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no repositories.

Method: GET

Path: /pulp/api/v2/repositories/

Permission: read

Query Parameters

details
(boolean) (optional) Shortcut for including both distributors and importers
importers
(boolean) (optional) Include the “importers” attribute on each repository
distributors
(boolean) (optional) Include the “distributors” attribute on each repository

Response Codes

200
Containing the array of repositories

Return: The same format as retrieving a single repository, except the base of the return value is an array of them

Sample 200 Response Body: 

[
 {
   "display_name": "Harness Repository: harness_repo_1",
   "description": null,
   "last_unit_added": "2012-01-25T15:26:32Z",
   "last_unit_removed": null,
   "distributors": [
     {
       "scratchpad": 1,
       "_ns": "repo_distributors",
       "last_publish": "2012-01-25T15:26:32Z",
       "auto_publish": false,
       "distributor_type_id": "harness_distributor",
       "repo_id": "harness_repo_1",
       "publish_in_progress": false,
       "_id": "addf9261-345e-4ce3-ad1e-436ba005287f",
       "config": {
         "publish_dir": "/tmp/harness-publish",
         "write_files": "true"
       },
       "id": "dist_1"
     }
   ],
   "notes": {},
   "scratchpad": {},
   "content_unit_counts": {},
   "importers": [
     {
       "scratchpad": 1,
       "_ns": "repo_importers",
       "importer_type_id": "harness_importer",
       "last_sync": "2012-01-25T15:26:32Z",
       "repo_id": "harness_repo_1",
       "sync_in_progress": false,
       "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e",
       "config": {
         "num_units": "5",
         "write_files": "true"
       },
       "id": "harness_importer"
     }
   ],
   "id": "harness_repo_1"
 }
]

D.1.2.3. Advanced Search for Repositories

See Search API for more details on how to perform these searches.

This call returns information on repositories in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned when there are no repositories.

Method: POST

Path: /pulp/api/v2/repositories/search/

Permission: read

Request Body Contents

details
(boolean) (optional) Shortcut to include “importers” and “distributors”
importers
(boolean) (optional) Include the “importers” attribute on each repository
distributors
(boolean) (optional) Include the “distributors” attribute on each repository

Response Codes

200
Containing the array of repositories

Return: The same format as retrieving a single repository, except the base of the return value is an array of them

Sample 200 Response Body: 

[
 {
   "display_name": "Harness Repository: harness_repo_1",
   "description": null,
   "distributors": [
     {
       "scratchpad": 1,
       "_ns": "repo_distributors",
       "last_publish": "2012-01-25T15:26:32Z",
       "auto_publish": false,
       "distributor_type_id": "harness_distributor",
       "repo_id": "harness_repo_1",
       "publish_in_progress": false,
       "_id": "addf9261-345e-4ce3-ad1e-436ba005287f",
       "config": {
         "publish_dir": "/tmp/harness-publish",
         "write_files": "true"
       },
       "id": "dist_1"
     }
   ],
   "notes": {},
   "scratchpad": {},
   "content_unit_counts": {},
   "last_unit_added": null,
   "last_unit_removed": null,
   "importers": [
     {
       "scratchpad": 1,
       "_ns": "repo_importers",
       "importer_type_id": "harness_importer",
       "last_sync": "2012-01-25T15:26:32Z",
       "repo_id": "harness_repo_1",
       "sync_in_progress": false,
       "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e",
       "config": {
         "num_units": "5",
         "write_files": "true"
       },
       "id": "harness_importer"
     }
   ],
   "id": "harness_repo_1"
 }
]

This call returns information on repositories in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no repositories.

This method is more limiting than the POST alternative because some filter expressions may not be serializable as query parameters.

Method: GET

Path: /pulp/api/v2/repositories/search/

Permission: read

Query Parameters

details
(boolean) (optional) Shortcut for including both distributors and importers
importers
(boolean) (optional) Include the importers attribute on each repository
distributors
(boolean) - (optional) Include the distributors attribute on each repository

Query parameters should match the attributes of a Criteria object as defined in Search Criteria. The exception is the fields parameter, which should be specified in singular form, for example: /v2/repositories/search/?field=id&field=display_name&limit=20’.

Response Codes

200
Vontaining the array of repositories

Return: The same format as retrieving a single repository, except the base of the return value is an array of them

Sample 200 Response Body: 

[
 {
   "display_name": "Harness Repository: harness_repo_1",
   "description": null,
   "distributors": [
     {
       "scratchpad": 1,
       "_ns": "repo_distributors",
       "last_publish": "2012-01-25T15:26:32Z",
       "auto_publish": false,
       "distributor_type_id": "harness_distributor",
       "repo_id": "harness_repo_1",
       "publish_in_progress": false,
       "_id": "addf9261-345e-4ce3-ad1e-436ba005287f",
       "config": {
         "publish_dir": "/tmp/harness-publish",
         "write_files": "true"
       },
       "id": "dist_1"
     }
   ],
   "notes": {},
   "scratchpad": {},
   "content_unit_counts": {},
   "last_unit_added": null,
   "last_unit_removed": null,
   "importers": [
     {
       "scratchpad": 1,
       "_ns": "repo_importers",
       "importer_type_id": "harness_importer",
       "last_sync": "2012-01-25T15:26:32Z",
       "repo_id": "harness_repo_1",
       "sync_in_progress": false,
       "_id": "bbe81308-ef7c-4c0c-b684-385fd627d99e",
       "config": {
         "num_units": "5",
         "write_files": "true"
       },
       "id": "harness_importer"
     }
   ],
   "id": "harness_repo_1"
 }
]

D.1.2.4. Retrieve importers associated with a repository

This call retrieves the importer (if any) associated with a repository. The array will be empty (no importer configured) or contain a single entry.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/importers/

Permission: read

Query Parameters: None

Response Codes

200
Containing an array of importers
404
If there is no repository with the given ID; this will not occur if the repository exists but has no associated importers.

Return: Database representation of the repository’s importer or an empty list

Sample 200 Response Body: 

[
   {
       "_href": "/pulp/api/v2/repositories/zoo/importers/yum_importer/",
       "_id": {
           "$oid": "563c82fa45ef48043f026c32"
       },
       "_ns": "repo_importers",
       "config": {
           "feed": "http://example.com/repos/zoo/"
       },
       "id": "yum_importer",
       "importer_type_id": "yum_importer",
       "last_sync": "2015-11-06T10:38:23Z",
       "repo_id": "zoo",
       "scratchpad": {
           "repomd_revision": 1331832478
       }
   }
]

D.1.2.5. Retrieve an importer associated with a repository

This call retrieves the given importer (if any) associated with a repository.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/

Permission: read

Query Parameters: None

Response Codes

200
Containing the details of the importer
404
If there is either no repository or importer with a matching ID

Return: Database representation of the repository’s importer

Sample 200 Response Body: 

{
   "_href": "/pulp/api/v2/repositories/zoo/importers/yum_importer/",
   "_id": {
       "$oid": "563c82fa45ef48043f026c32"
   },
   "_ns": "repo_importers",
   "config": {
       "feed": "http://example.com/repos/zoo/"
   },
   "id": "yum_importer",
   "importer_type_id": "yum_importer",
   "last_sync": "2015-11-06T10:38:23Z",
   "repo_id": "zoo",
   "scratchpad": {
       "repomd_revision": 1331832478
   }
}

D.1.2.6. Retrieve distributors associated with a repository

This call retrieves all distributors associated with a repository. If the repository has no associated distributors, an empty array is returned.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/distributors/

Permission: read

Query Parameters: None

Response Codes

200
Containing an array of distributors
404
If there is no repository with the given ID; this will not occur if the repository exists but has no associated distributors

Return: Database representations of all distributors on the repository

Sample 200 Response Body: 

[
 {
   "scratchpad": 1,
   "_ns": "repo_distributors",
   "last_publish": "2012-01-25T15:26:32Z",
   "auto_publish": false,
   "distributor_type_id": "harness_distributor",
   "repo_id": "harness_repo_1",
   "publish_in_progress": false,
   "_id": "addf9261-345e-4ce3-ad1e-436ba005287f",
   "config": {
     "publish_dir": "/tmp/harness-publish",
     "write_files": "true"
   },
   "id": "dist_1"
 }
]

D.1.2.7. Retrieve a distributor associated with a repository

This call retrieves a single distributor associated with a repository.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/

Permission: read

Query Parameters: None

Response Code

200
Containing the details of a distributors
404
If there is either no repository or distributor with a matching ID.

Return: Database representation of the distributor

Sample 200 Response Body: 

{
  "scratchpad": 1,
  "_ns": "repo_distributors",
  "last_publish": "2012-01-25T15:26:32Z",
  "auto_publish": false,
  "distributor_type_id": "harness_distributor",
  "repo_id": "harness_repo_1",
  "publish_in_progress": false,
  "_id": {"$oid": "addf9261-345e-4ce3-ad1e-436ba005287f"},
  "config": {
    "publish_dir": "/tmp/harness-publish",
    "write_files": "true"
  },
  "id": "dist_1"
}

D.1.2.8. Advanced search for distributors

See Search API for more details on how to perform these searches.

This call returns information on distributors in the Pulp server that match your search parameters. It is worth noting that this call never returns a 404; an empty array is returned in the case where there are no distributors.

Method: POST

Path: /pulp/api/v2/distributors/search/

Permission: read

Request Body Contents: None

Response Codes

200
Containing the array of distributors

Return: A list of distributor objects

Sample 200 Response Body: 

[
  {
    "repo_id": "el7",
    "last_publish": "2015-04-28T18:19:01Z",
    "auto_publish": null,
    "scheduled_publishes": [],
    "distributor_type_id": "ostree_web_distributor",
    "scratchpad": null,
    "config": {
      "relative_path": "/opt/content/ostree/el7"
    },
    "id": "ostree_web_distributor_name_cli"
  },
  {
    "repo_id": "el6",
    "last_publish": "2015-5-28T18:18:01Z",
    "auto_publish": null,
    "scheduled_publishes": [],
    "distributor_type_id": "ostree_web_distributor",
    "scratchpad": null,
    "config": {
      "relative_path": "/opt/content/ostree/el6"
    },
    "id": "ostree_web_distributor_name_cli"
  }
]

D.1.3. Synchronization

D.1.3.1. Sync a repository

This call syncs content into a repository from a feed source using the repository’s importer.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/actions/sync/

Permission: execute

Request Body Contents

override_config
(object) (optional) Importer configuration values that override the importer’s default configuration for this sync

Response Codes

202
If the sync is set to be executed
404
If repo does not exist

Return: A Call Report

Sample Request: 

{
  "override_config": {"verify_checksum": false,
                      "verify_size": false},
}

Tags: The task created has the following tags: pulp:action:sync, pulp:repository:<repo_id>

D.1.3.2. Download a Repository

This call downloads content into a repository that was deferred at sync time. This is useful for repositories with importers that are configured with download_policy=(background | on_demand). Content that has already been downloaded will not be downloaded again.

Note

This API requires that the Alternate Download Policies features must be installed and configured to work. If it has not been configured, the task dispatched by this API does nothing.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/actions/download/

Permission: execute

Request Body Contents

verify_all_units
(boolean) (optional) Check all units in the repository for corrupted or missing files and download files as necessary rather than just downloading files that are known to be missing (defaults to false)

Response Codes

202
If the download is set to be executed
404
If the repository does not exist

Return: A Call Report

Sample Request: 

{
  "verify_all_units": false
}

Tags: The task created will have the following tags: pulp:action:download_repo, pulp:repository:<repo_id>

D.1.3.3. Scheduling a Sync

A repository can be synced automatically using an iso8601 interval. To create a scheduled sync, the interval, sync override config, and other schedule options must be set on the repository’s importer.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/

Permission: create

Request Body Contents

schedule
(string) The schedule as an iso8601 interval
override_config
(object) (optional) The overridden configuration for the importer to be used on the scheduled sync

failure_threshold (number) (optional) Consecutive failures allowed before this scheduled sync is disabled

enabled
(boolean) (optional) Whether the scheduled sync is initially enabled (defaults to true)

Response Codes

201
If the schedule was successfully created
400
If one or more of the parameters are invalid
404
If there is no repository or importer with the specified IDs

Return: schedule report representing the current state of the scheduled call

Sample Request: 

{
 "override_config": {},
 "schedule": "00:00:00Z/P1DT",
 "failure_threshold": 3,
}

Sample 201 Response Body: 

{
 "next_run": "2014-01-27T21:41:50Z",
 "task": "pulp.server.tasks.repository.sync_with_auto_publish",
 "last_updated": 1390858910.292712,
 "first_run": "2014-01-27T21:41:50Z",
 "schedule": "PT1H",
 "args": [
   "demo"
 ],
 "enabled": true,
 "last_run_at": null,
 "_id": "52e6d29edd01fb70bd0d9c37",
 "total_run_count": 0,
 "failure_threshold": 3,
 "kwargs": {
   "overrides": {}
 },
 "resource": "pulp:importer:demo:puppet_importer",
 "remaining_runs": null,
 "consecutive_failures": 0,
 "_href": "/pulp/api/v2/repositories/demo/importers/puppet_importer/schedules/sync/52e6d29edd01fb70bd0d9c37/"
}

D.1.3.4. Updating a scheduled sync

The same parameters used to create a scheduled sync may be updated at any point.

Method: PUT

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/

Permission: create

Request Body Contents

schedule
(string) (optional) New schedule as an iso8601 interval
override_config
(object) (optional) New overridden configuration for the importer to be used on the scheduled sync

failure_threshold (number) (optional) New consecutive failures allowed before this scheduled sync is disabled

enabled
(boolean) (optional) Whether the scheduled sync is enabled

Response Codes

200
If the schedule was successfully updated
400
If one or more of the parameters are invalid
404
If there is no repository, importer or schedule with the specified IDs

Return: Schedule report representing the current state of the scheduled call (See sample response of Scheduling a Sync for details.)

D.1.3.5. Deleting a Scheduled Sync

Delete a scheduled sync to remove it permanently from the importer.

Method: DELETE

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/

Permission: delete

Response Codes

200
If the schedule was deleted successfully
404
If there is no repository, importer or schedule with the specified IDs

Return: null

D.1.3.6. Listing All Scheduled Syncs

All of the scheduled syncs for a given importer may be listed.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/

Permission: read

Response Codes

200
If repo, importer exist
404
If there is no repository or importer with the specified IDs

Return: array of schedule reports for all scheduled syncs defined

Sample 200 Response Body: 

[
   {
       "_href": "/pulp/api/v2/repositories/test/importers/yum_importer/schedules/sync/54d8852245ef4876fade7cc2/",
       "_id": "54d8852245ef4876fade7cc2",
       "args": [
           "test"
       ],
       "consecutive_failures": 0,
       "enabled": true,
       "failure_threshold": null,
       "first_run": "2015-02-09T10:00:02Z",
       "kwargs": {
           "overrides": {}
       },
       "last_run_at": "2015-02-09T10:00:23Z",
       "last_updated": 1423476133.825821,
       "next_run": "2015-02-10T10:00:02Z",
       "remaining_runs": null,
       "resource": "pulp:importer:test:yum_importer",
       "schedule": "P1DT",
       "task": "pulp.server.tasks.repository.sync_with_auto_publish",
       "total_run_count": 1
   }
]

D.1.3.7. Listing a single scheduled sync

Each scheduled sync may be inspected.

Method: GET

Permission: read

Path: /pulp/api/v2/repositories/<repo_id>/importers/<importer_id>/schedules/sync/<schedule_id>/

Response Codes

200
If repo, importer, schedule exist
404
If there is no repository, importer or schedule with the specified IDs

Return: A schedule report for the scheduled sync

Sample 200 Response Body: 

{
   "_href": "/pulp/api/v2/repositories/test/importers/yum_importer/schedules/sync/54d8852245ef4876fade7cc2/",
   "_id": "54d8852245ef4876fade7cc2",
   "args": [
       "test"
   ],
   "consecutive_failures": 0,
   "enabled": true,
   "failure_threshold": null,
   "first_run": "2015-02-09T10:00:02Z",
   "kwargs": {
       "overrides": {}
   },
   "last_run_at": "2015-02-09T10:00:23Z",
   "last_updated": 1423476133.825821,
   "next_run": "2015-02-10T10:00:02Z",
   "remaining_runs": null,
   "resource": "pulp:importer:test:yum_importer",
   "schedule": "P1DT",
   "task": "pulp.server.tasks.repository.sync_with_auto_publish",
   "total_run_count": 1
}

D.1.3.8. Retrieving sync history

This call retrieves sync history for a repository. Each sync performed on a repository creates a history entry.

Method: GET

Permission: read

Path: /pulp/api/v2/repositories/<repo_id>/history/sync/

Query Parameters

limit
(integer) (optional) The maximum number of history entries to return; if not specified, the entire history is returned
sort
(string) (optional) Options are ‘ascending’ and ‘descending’; the array is sorted by the sync timestamp
start_date
(iso8601 datetime) (optional) Any entries with a timestamp prior to the given date are not returned
end_date
(iso8601 datetime) (optional) Any entries with a timestamp after the given date are not returned

Response Codes

200
If the history was successfully retrieved
404
If the repository id given does not exist

Return: An array of sync history entries

Sample 200 Response Body: 

[
 {
  "result": "success",
  "importer_id": "my_demo_importer",
  "exception": null,
  "repo_id": "demo_repo",
  "traceback": null,
  "started": "1970:00:00T00:00:00Z",
  "completed": "1970:00:00T00:00:01Z",
  "importer_type_id": "demo_importer",
  "error_message": null,
 }
]

D.1.4. Publication

D.1.4.1. Publish a repository

This call publishes content from a repository using a repository’s distributor. This call always executes asynchronously and returns a Call Report.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/actions/publish/

Permission: execute

Request Body Contents

id
(string) Identifies which distributor on the repository to publish
override_config
(object) (optional) Distributor configuration values that override the distributor’s default configuration for this publish

Response Codes

202
If the publish is set to be executed
404
If repo does not exist

Return: A Call Report representing the current state of the sync

Sample Request: 

{
  "id": "distributor_1",
  "override_config": {},
}

Tags: The task created has the following tags: pulp:action:publish, pulp:repository:<repo_id>

D.1.4.2. Scheduling a publish

A repository can be published automatically using an iso8601 interval. To create a scheduled publish, the interval, publish override config, and other schedule options must be set on a repository’s distributor.

Method: POST

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/

Permission: create

Request Body Contents

schedule
(string) The schedule as an iso8601 interval
override_config
(object) (optional) The overridden configuration for the distributor to be used on the scheduled publish
failure_threshold
(number) (optional) Consecutive failures allowed before this scheduled publish is disabled
enabled
(boolean) (optional) Whether the scheduled publish is initially enabled (defaults to true)

Response Codes

201
If the schedule was successfully created
400
If one or more of the parameters are invalid
404
If there is no repository or distributor with the specified IDs

Return: Schedule report representing the current state of the scheduled call

Sample Request: 

{
 "override_config": {},
 "schedule": "PT1H",
 "failure_threshold": 3,
}

Sample 201 Response Body: 

{
 "next_run": "2014-01-27T21:27:56Z",
 "task": "pulp.server.tasks.repository.publish",
 "last_updated": 1390858076.682694,
 "first_run": "2014-01-27T21:27:56Z",
 "schedule": "PT1H",
 "args": [
   "demo",
   "puppet_distributor"
 ],
 "enabled": true,
 "last_run_at": null,
 "_id": "52e6cf5cdd01fb70bd0d9c34",
 "total_run_count": 0,
 "failure_threshold": 3,
 "kwargs": {
   "overrides": {}
 },
 "resource": "pulp:distributor:demo:puppet_distributor",
 "remaining_runs": null,
 "consecutive_failures": 0,
 "_href": "/pulp/api/v2/repositories/demo/distributors/puppet_distributor/schedules/publish/52e6cf5cdd01fb70bd0d9c34/"
}

D.1.4.3. Updating a scheduled publish

The same parameters used to create a scheduled publish may be updated at any point.

Method: PUT

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/

Permission: create

Request Body Contents

schedule
(string) (optional) New schedule as an iso8601 interval
override_config
(object) (optional) New overridden configuration for the importer to be used on the scheduled sync
failure_threshold
(number) (optional) New consecutive failures allowed before this scheduled sync is disabled
enabled
(boolean) (optional) Whether the scheduled sync is enabled

Response Codes

200
If the schedule was successfully updated

400: If one or more of the parameters are invalid

404: If there is no repository, distributor or schedule with the specified IDs

Return: Schedule report representing the current state of the scheduled call (See sample response of Scheduling a Publish for details.)

D.1.4.4. Deleting a scheduled publish

Delete a scheduled publish to remove it permanently from the distributor.

Method: DELETE

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/

Permission: delete

Response Codes

200
If the schedule was deleted successfully
404
If there is no repository, distributor or schedule with the specified IDs

Return: null

D.1.4.5. Listing all scheduled publishes

All of the scheduled publishes for a given distributor may be listed.

Method: GET

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/

Permission: read

Response Codes

200
If there is a repository, a distributor exists
404
If there is not repository or distributor with the specified IDs

Return: Array of schedule reports for all scheduled publishes defined (See sample response of Scheduling a Publish for details.)

Sample 200 Response Body: 

{
    "_href": "/pulp/api/v2/repositories/test/distributors/yum_distributor/schedules/publish/54d88df045ef4876fb50c994/",
    "_id": "54d88df045ef4876fb50c994",
    "args": [
        "test",
        "yum_distributor"
    ],
    "consecutive_failures": 0,
    "enabled": true,
    "failure_threshold": null,
    "first_run": "2015-02-09T10:37:36Z",
    "kwargs": {
        "overrides": {}
    },
    "last_run_at": "2015-02-09T10:38:23Z",
    "last_updated": 1423478256.805917,
    "next_run": "2015-02-10T10:37:36Z",
    "remaining_runs": null,
    "resource": "pulp:distributor:test:yum_distributor",
    "schedule": "P1DT",
    "task": "pulp.server.tasks.repository.publish",
    "total_run_count": 1
}

D.1.4.6. Listing a single scheduled publish

Each scheduled publish may be inspected.

Method: GET

Permission: read

Path: /pulp/api/v2/repositories/<repo_id>/distributors/<distributor_id>/schedules/publish/<schedule_id>/

Response Codes:

200
If there is a repository, a distributor or schedule exists
404
If there is not a repository, distributor or schedule with the specified IDs

Return: A schedule report for the scheduled publish (See sample response of Scheduling a Publish for details.)

Sample 200 Response Body: 

{
   "_href": "/pulp/api/v2/repositories/test/distributors/yum_distributor/schedules/publish/54d88df045ef4876fb50c994/",
   "_id": "54d88df045ef4876fb50c994",
   "args": [
       "test",
       "yum_distributor"
   ],
   "consecutive_failures": 0,
   "enabled": true,
   "failure_threshold": null,
   "first_run": "2015-02-09T10:37:36Z",
   "kwargs": {
       "overrides": {}
   },
   "last_run_at": "2015-02-09T10:38:23Z",
   "last_updated": 1423478256.805917,
   "next_run": "2015-02-10T10:37:36Z",
   "remaining_runs": null,
   "resource": "pulp:distributor:test:yum_distributor",
   "schedule": "P1DT",
   "task": "pulp.server.tasks.repository.publish",
   "total_run_count": 1
}

D.1.4.7. Retrieving publish history

This call retrieves publish history for a repository. Each publish performed on a repository creates a history entry.

Method: GET

Permission: read

Path: /pulp/api/v2/repositories/<repo_id>/history/publish/<distributor_id>/

Query Parameters

limit
(integer) (optional) The maximum number of history entries to return; if not specified, the entire history is returned.
sort
(string) (optional) Options are ‘ascending’ and ‘descending’; the array is sorted by the publish timestamp.

start_date (iso8601 datetime) (optional) Any entries with a timestamp prior to the given date are not returned.

end_date
(iso8601 datetime) (optional) Any entries with a timestamp after the given date are not returned.

Response Codes

200
If the history was successfully retrieved

404: If the repository id given does not exist

Return: An array of publish history entries

Sample 200 Response Body: 

[
 {
  "result": "success",
  "distributor_id": "my_demo_distributor",
  "distributor_type_id": "demo_distributor",
  "exception": null,
  "repo_id": "demo_repo",
  "traceback": null,
  "started": "1970:00:00T00:00:00Z",
  "completed": "1970:00:00T00:00:01Z",
  "error_message": null,
 }
]

D.1.5. Content retrieval

D.2. Task management

Pulp can execute almost any call asynchronously, and some calls are always executed asynchronously. Pulp provides REST APIs to inspect and manage the tasks executing these calls.

D.2.1. Task report

The task information object is used to report information about any asynchronously executed task.

Task information object

_href
(string) URI path to retrieve this task report object
state
(string) The current state of the task; the possible values include waiting, skipped, ‘running, suspended, finished, error, and canceled.
task_id
(string) The unique ID of the task that is executing the asynchronous call
task_type
(string) Deprecated the fully qualified (package/method) type of the task that is executing the asynchronous call; the field is empty for tasks performed by consumer agent.
progress_report
(object) Arbitrary progress information, usually in the form of an object
result
(any) The return value of the call, if any
exception
(null or string) Deprecated the error exception value, if any
traceback
(null or array) Deprecated the resulting traceback if an exception was raised
start_time
(null or string) The time the call started executing
finish_time
(null or string) The time the call stopped executing
tags
(array) Arbitrary tags useful for looking up the Call Report
spawned_tasks
(array) List of objects containing the URI and task ID for any tasks that were spawned by this task
worker_name
(string) The worker associated with the task; this field is empty if a worker is not yet assigned.
queue
(string) The queue associated with the task; this field is empty if a queue is not yet assigned.
error
(null or object) Any errors that occurred that did not cause the overall call to fail. See Error Details.
Note

The exception and traceback fields have been deprecated as of Pulp 2.4. The information about errors that have occurred will be contained in the error block. See Error Details for more information.

Example Task Report: 

{
 "_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/",
 "state": "running",
 "worker_name": "reserved_resource_worker-0@your.domain.com",
 "task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff",
 "task_type": "pulp.server.tasks.repository.sync_with_auto_publish",
 "progress_report": {}, # contents depend on the operation
 "result": null,
 "start_time": "2012-05-17T16:48:00Z",
 "finish_time": null,
 "exception": null,
 "traceback": null,
 "tags": [
   "pulp:repository:f16",
   "pulp:action:sync"
 ],
 "spawned_tasks": [{"href": "/pulp/api/v2/tasks/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
                    "task_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b" }],
 "error": null
}

D.2.2. Polling task progress

Poll a task for progress and result information for the asynchronous call it is executing. Polling returns a Task Report.

Method: GET

Path: /pulp/api/v2/tasks/<task_id>/

Permission: read

Response Codes

200
If the task is found
404
If the task is not found

Return: A Task Report representing the task queried

D.2.3. Canceling a task

Some asynchronous tasks may be canceled by the user before they complete. A task must be in the waiting or running states in order to be canceled.

Note

It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be canceled as a result of this call. In these instances, this method call will still return a response code of 200.

Method: DELETE

Path: /pulp/api/v2/tasks/<task_id>/

Permission: delete

Response Codes

200
If the task cancellation request was successfully received
404
If the task is not found

Return: null

D.2.4. Listing tasks

All currently running and waiting tasks may be listed. This returns an array of Task Report instances. the array can be filtered by tags.

Method: GET

Path: /pulp/api/v2/tasks/

Permission: read

Query Parameters

tag
(string) (optional) Only return tasks tagged with all tag parameters

Response Codes

200
Containing an array of tasks

Return: Array of Task Report

D.2.5. Deleting completed tasks

All completed tasks with states finished, error, skipped can be deleted. This call returns response code 204 if successful or code 403 if the request is forbidden.

Method: DELETE

Path: /pulp/api/v2/tasks/

Permission: delete

state
(string) (optional) Only delete tasks currently in this state

For example:

/pulp/api/v2/tasks/?state=finished&state=skipped

Response Codes

204
if the tasks were successfully deleted
403
If there was a forbidden request

Return: http Response or pulp Exception

D.2.6. Searching for tasks

API callers may also search for tasks. This uses a search criteria document.

Method: POST

Path: /pulp/api/v2/tasks/search/

Permission: read

Request Body Contents: Include the key criteria, whose value is a mapping structure as defined in Search Criteria.

Response Codes

200
Containing the list of tasks

Return: The same format as retrieving a single task, except the base of the return value is a list; if no results are found, an empty list is returned.

Method: GET

Path: /pulp/api/v2/tasks/search/

Permission: read

Query Parameters: Query parameters should match the attributes of a Criteria object as defined in Search Criteria. The exception is that field names should be specified in singular form with as many ‘field=foo’ pairs as needed.

For example:

/pulp/api/v2/tasks/search/?field=id&field=task_type&limit=20

Response Codes

200
Containing the array of tasks

D.3. Task group management

D.3.1. Canceling tasks in a task group

All asynchronous tasks in a particular task group can be canceled by the user before they complete. A task must be in the waiting or running state to be canceled.

Note

=== It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be canceled as a result of this call. In these instances, this method call will still return a response code of 200. ===

Method: DELETE

Path: /pulp/api/v2/task_groups/<group_id>/

Permission: delete

Response Codes

200
If the task group cancellation request was successfully received
404
If the task group is not found

Return: null

D.3.2. Task group summary

The Task Group Summary object summarizes the state of all the tasks belonging to a task group.

Task Group Summary object

accepted
(int) Number of tasks in accepted state
finished
(int) Number of tasks in finished state
running
(int) Number of tasks in running state
canceled
(int) Number of tasks in canceled state
waiting
(int) Number of tasks in waiting state
skipped
(int) Number of tasks in skipped state
suspended
(int) Number of tasks in suspended state
error
(int) Number of tasks in error state
tota
(int) Total number of tasks in the task group

Example task group summary: 

{
 "accepted": 0,
 "finished": 100,
 "running": 4,
 "canceled": 0,
 "waiting": 2,
 "skipped": 0,
 "suspended": 0,
 "error": 0,
 "total": 106
}

D.3.3. Polling task group progress

Poll a group of tasks for progress summary. Polling returns a Cancelling Tasks in a Task Group.

Method: GET

Path: /pulp/api/v2/task_groups/<task_group_id>/state_summary/

Permission: read

Response Codes

200
If the task group is found
404
If the task group id is not found

Return: A Cancelling Tasks in a Task Group summarizing the state of all tasks belonging to queried task group ID

Report a bug