README-2.0.0.md in ruby-jss-2.0.0a11 vs README-2.0.0.md in ruby-jss-2.0.0b1

- old
+ new

@@ -6,40 +6,42 @@ These changes have been in mind for some time, but the ability (soon to be requirement) for the Classic API to authenticate with Bearer Tokens from the Jamf Pro API means that the time has come, so here we are! **CONTENTS** -<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 --> +<!-- TOC --> -- [Requirements](#requirements) -- [High level changes](#high-level-changes) - - [Ruby 3.x support](#ruby-3x-support) - - [Combined API access](#combined-api-access) - - [A single Connection class](#a-single-connection-class) - - [Connecting to the API](#connecting-to-the-api) - - [The default connection](#the-default-connection) - - [A single namespace `Jamf`](#a-single-namespace-jamf) - - [Inherant differences between the APIs](#inherant-differences-between-the-apis) - - [Which API does an object come from?](#which-api-does-an-object-come-from) - - [Automatic code generation](#automatic-code-generation) - - [Autoloading with Zeitwerk](#autoloading-with-zeitwerk) -- [Notable changes from ruby-jss 1.x](#notable-changes-from-ruby-jss-1x) - - [Paged queries to the Jamf Pro API](#paged-queries-to-the-jamf-pro-api) - - [API data are no longer cached (?)](#api-data-are-no-longer-cached-) - - [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects) - - [Class/Mixin hierarchy for Jamf Pro API objects](#classmixin-hierarchy-for-jamf-pro-api-objects) -- [Planned deprecations](#planned-deprecations) - - [Use of the term 'api' in method names, parameter names, and attributes](#use-of-the-term-api-in-method-names-parameter-names-and-attributes) - - [`.map_all_ids_to` method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes) - - [Using `.make`, `#create`, and `#update` for Classic API objects](#using-make-create-and-update-for-classic-api-objects) - - [JSS::CONFIG](#jssconfig) - - [Jamf::Connection instance methods `#next_refresh`, `#secs_to_refresh`, & `#time_to_refresh`](#jamfconnection-instance-methods-next_refresh-secs_to_refresh---time_to_refresh) - - [Cross-object validation in setters](#cross-object-validation-in-setters) - - [.fetch :random](#fetch-random) -- [Documentation](#documentation) -- [How to install for testing](#how-to-install-for-testing) -- [Contact](#contact) +- [ruby-jss 2.0: Combined access to the Classic and Jamf Pro APIs](#ruby-jss-20-combined-access-to-the-classic-and-jamf-pro-apis) + - [Requirements](#requirements) + - [High level changes](#high-level-changes) + - [Ruby 3.x support](#ruby-3x-support) + - [Combined API access](#combined-api-access) + - [A single Connection class](#a-single-connection-class) + - [Connecting to the API](#connecting-to-the-api) + - [The default connection](#the-default-connection) + - [A single namespace Jamf](#a-single-namespace-jamf) + - [Inherant differences between the APIs](#inherant-differences-between-the-apis) + - [Which API does an object come from?](#which-api-does-an-object-come-from) + - [Automatic code generation](#automatic-code-generation) + - [Autoloading with Zeitwerk](#autoloading-with-zeitwerk) + - [Notable changes from ruby-jss 1.x](#notable-changes-from-ruby-jss-1x) + - [Paged queries to the Jamf Pro API](#paged-queries-to-the-jamf-pro-api) + - [API data are no longer cached ?](#api-data-are-no-longer-cached-) + - [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects) + - [Class/Mixin hierarchy for Jamf Pro API objects](#classmixin-hierarchy-for-jamf-pro-api-objects) + - [Support for 'Sticky Sessions' in Jamf Cloud](#support-for-sticky-sessions-in-jamf-cloud) + - [Planned deprecations](#planned-deprecations) + - [Use of the term 'api' in method names, parameter names, and attributes](#use-of-the-term-api-in-method-names-parameter-names-and-attributes) + - [.map_all_ids_to method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes) + - [Using .make, #create, and #update for Classic API objects](#using-make-create-and-update-for-classic-api-objects) + - [JSS::CONFIG](#jssconfig) + - [Jamf::Connection instance methods #next_refresh, #secs_to_refresh, & #time_to_refresh](#jamfconnection-instance-methods-next_refresh-secs_to_refresh---time_to_refresh) + - [Cross-object validation in setters](#cross-object-validation-in-setters) + - [fetch :random](#fetch-random) + - [Documentation](#documentation) + - [How to install for testing](#how-to-install-for-testing) + - [Contact](#contact) <!-- /TOC --> ## Requirements @@ -49,11 +51,11 @@ ## High level changes ### Ruby 3.x support -The plan is for ruby-jss 2.0+ to be compatible with ruby 2.7 and higher, including ruby 3.x +The plan is for ruby-jss 2.0+ to be compatible with ruby 2.6.3 and higher, including ruby 3.x As of this writing, basic access to the API seems to be working in ruby 3, but much much more testing is needed. It looks like the biggest changes have been dealing with keyword arguments as Hashs. Methods defined with `def methodname([...] foo = {}` need to be changed to `def methodname([...] **foo` and calls to those methods, even in your own code, need to be changed to `methodname([...] **foo)` when `foo` is a hash of keyword args. @@ -123,11 +125,11 @@ If you develop ruby-jss, please see (documentation link TBA) for more info about how to use the auto-generated classes. ### Autoloading with Zeitwerk -Because the classes generated from the OAPI spec number in the hundreds, it's a waste of memory and time to load all of them in every time you `require ruby-jss`, since most of them will never be used for any given application. +Because the classes generated from the OAPI spec number in the hundreds, it's a waste of memory and time to load all of them in every time you `require 'ruby-jss'`, since most of them will never be used for any given application. To deal with this, ruby-jss now uses the wonderfully cool [Zeitwerk gem](https://github.com/fxn/zeitwerk) to automatically load only the files needed for classes and modules as they are used. In fact, if you'd like to see it in action, just `touch /tmp/ruby-jss-verbose-loading` or `export RUBY_JSS_VERBOSE_LOADING=1` before you `require ruby-jss`. Then as files load, lines will be written to standard error indicating: @@ -174,9 +176,20 @@ If you contribute to ruby-jss, be aware that the structure of superclasses, subclasses, and mixin modules, and their file locations has changed drastically. Also changed is how to implement new objects using the OAPI auto-generated classes. These changes are due to using the auto-generated classes, as well as using Zeitwerk to autoload everything. There's a lot to document about these changes, and much of the current documentation is out of date, referring to how things were done when the Jamf module was separate and only talked to the Jamf Pro API. Give us time and we'll get everything updated. In the meantime, feel free to reach out in the #ruby-jss channel of Macadmins Slack, or open an issue on GitHub, or email ruby-jss@pixar.com. + +### Support for 'Sticky Sessions' in Jamf Cloud + +If you are connecting to a Jamf Cloud server, you can specifcy `sticky_sessions: true` when calling `Jamf::Connection.new` or `Jamf::Connection#connect`. If you already have a connected Connection object, you can enable or disable Sticky Sessions using `my_connection_object.sticky_session =` with a boolean value (for the default connection use `Jamf.cnx.sticky_session = <boolean>`). To see the actual cookie being sent to enable sticky sessions, use `Jamf::Connection#sticky_session_cookie`. + +Attempting to enable a sticky session with a connection to an on-prem server (host not ending in 'jamfcloud.com') will raise an error. + +For details about Sticky Sessions see [Sticky Sessions for Jamf Cloud](https://developer.jamf.com/developer-guide/docs/sticky-sessions-for-jamf-cloud) at the Jamf Developer site. + +**WARNING:** Jamf recommends NOT using sticky sessions unless they are needed. Using them inappropriately may negatively impact performance, especially for large automated processes. + ## Planned deprecations ### Use of the term 'api' in method names, parameter names, and attributes