Bug 1309791

Summary:	[RFE] Expand Examples in the API guide to include the 'page', 'per_page', and other modifiers.
Product:	Red Hat Satellite	Reporter:	Rich Jerrido <rjerrido>
Component:	Documentation	Assignee:	Melanie Corr <mcorr>
Status:	CLOSED WORKSFORME	QA Contact:	satellite-doc-list
Severity:	medium	Docs Contact:
Priority:	medium
Version:	6.1.5	CC:	adahms, adprice, erinn.looneytriggs, ltsai, mcorr, swadeley
Target Milestone:	Unspecified	Keywords:	FutureFeature
Target Release:	Unused
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Enhancement
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2019-11-05 09:33:08 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:	1138262, 1410746, 1417726
Bug Blocks:

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