Red Hat Satellite engineering is moving the tracking of its product development work on Satellite to Red Hat Jira (issues.redhat.com). If you're a Red Hat customer, please continue to file support cases via the Red Hat customer portal. If you're not, please head to the "Satellite project" in Red Hat Jira and file new tickets here. Individual Bugzilla bugs will be migrated starting at the end of May. If you cannot log in to RH Jira, please consult article #7032570. That failing, please send an e-mail to the RH Jira admins at rh-issues@redhat.com to troubleshoot your issue as a user management inquiry. The email creates a ServiceNow ticket with Red Hat. Individual Bugzilla bugs that are migrated will be moved to status "CLOSED", resolution "MIGRATED", and set with "MigratedToJIRA" in "Keywords". The link to the successor Jira issue will be found under "Links", have a little "two-footprint" icon next to it, and direct you to the "Satellite project" in Red Hat Jira (issue links are of type "https://issues.redhat.com/browse/SAT-XXXX", where "X" is a digit). This same link will be available in a blue banner at the top of the page informing you that that bug has been migrated.
Bug 1309791 - [RFE] Expand Examples in the API guide to include the 'page', 'per_page', and other modifiers.
Summary: [RFE] Expand Examples in the API guide to include the 'page', 'per_page', and...
Keywords:
Status: CLOSED WORKSFORME
Alias: None
Product: Red Hat Satellite
Classification: Red Hat
Component: Documentation
Version: 6.1.5
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: Unspecified
Assignee: Melanie Corr
QA Contact: satellite-doc-list
URL:
Whiteboard:
Depends On: 1138262 1410746 1417726
Blocks:
TreeView+ depends on / blocked
 
Reported: 2016-02-18 17:28 UTC by Rich Jerrido
Modified: 2019-11-05 09:33 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: Enhancement
Doc Text:
Clone Of:
Environment:
Last Closed: 2019-11-05 09:33:08 UTC
Target Upstream Version:
Embargoed:

Attachments (Terms of Use)

Description Rich Jerrido 2016-02-18 17:28:03 UTC 
Document URL: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/API_Guide/index.html#chap-Red_Hat_Satellite-API_Guide-Examples


Section Number and Name: 4. Examples. 

Describe the issue: 


In the examples, we do not state to the end-user how to modify the output that the API returns. As an example, it is considered good practice to limit to amount of data returned, so as to not put unnecessary load on the server. 

This requires the end-user to use the '?page' & '?per_page' options to retrieve the data in chunks. However, the API Guide does not inform the user of this. 

Suggestions for improvement: 

Document the following options (as viewable in /apidoc/ on the Satellite)

search - search string
page - Page number, starting at 1
per_page - Number of results per page to return
order - Sort field and order, eg. 'name DESC'
full_results - Whether or not to show all results
sort - Hash version of 'order' param
sort[by] - Field to sort the results on
sort[order] - How to order the sorted results (e.g. ASC for ascending)

Additional information:
Comment 1 David O'Brien 2016-02-22 22:53:30 UTC 
Adding Adam as general SME for API material.
Comment 2 Stephen Wadeley 2017-01-03 14:59:04 UTC 
Hello 

As a result of another bug I recently added

Using Searches with Pagination Control — https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/api-guide/45-using-searches-with-pagination-control


however it does not cover all the points mentioned in comment 0
Comment 3 Stephen Wadeley 2017-01-06 11:22:36 UTC 
(In reply to Rich Jerrido from comment #0)
> Document URL:
> https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-
> single/API_Guide/index.html#chap-Red_Hat_Satellite-API_Guide-Examples
> 
> 
> Section Number and Name: 4. Examples. 
> 
> Describe the issue: 
> 

> 
> Suggestions for improvement: 
> 
> Document the following options (as viewable in /apidoc/ on the Satellite)
> 
> search - search string
For the above we need this bug to be resolved: Bug 1410746
setting it to block this bug


> page - Page number, starting at 1
> per_page - Number of results per page to return
> order - Sort field and order, eg. 'name DESC'
> full_results - Whether or not to show all results
> sort - Hash version of 'order' param
> sort[by] - Field to sort the results on
> sort[order] - How to order the sorted results (e.g. ASC for ascending)
> 
the rest of the items I should be able to get from upstream here:
https://theforeman.org/manuals/1.13/index.html#5.1.2JSONResponseFormatforCollections
Comment 9 Andrew Dahms 2018-11-06 05:31:06 UTC 
Updating release flags and returning to the default assignee to be reviewed as the schedule allows.
Comment 10 Melanie Corr 2019-11-05 09:33:08 UTC 
This is a rather old bug, and on review, I think that a lot of the ground work for this was done as part of other work carried out by Stephen Wadeley and Sergei Petrosian in phases. 

Pagination is explained here:

https://access.redhat.com/documentation/en-us/red_hat_satellite/6.6/html/api_guide/chap-red_hat_satellite-api_guide-using_the_red_hat_satellite_api#sect-API-Guide-Using_Searches_with_Pagination_Control

The response formats are explained here:


https://access.redhat.com/documentation/en-us/red_hat_satellite/6.6/html/api_guide/chap-red_hat_satellite-api_guide-api_reference#sect-API_Guide-Understanding_the_JSON_Response_Format
Note You need to log in before you can comment on or make changes to this bug.