Module: Chef::DSL::RestResource

Defined in:
lib/chef/dsl/rest_resource.rb

Overview

DSL methods for configuring REST resource behavior. These methods are available when a custom resource uses the 'core::rest_resource' partial.

Instance Method Summary collapse

Instance Method Details

#rest_api_collection(rest_api_collection = NOT_PASSED) ⇒ String

Define the REST API collection URL

Sets the base URL for the collection of resources. This URL is used for:

  • GET requests to list all resources
  • POST requests to create new resources

Examples:

rest_api_collection '/api/v1/users'
# GET  /api/v1/users      # List all users
# POST /api/v1/users      # Create new user

Raises:

  • (ArgumentError) —

    If the path doesn't start with '/'



85
86
87
88
89
90
91
92
93
 
# File 'lib/chef/dsl/rest_resource.rb', line 85

def rest_api_collection(rest_api_collection = NOT_PASSED)
  if rest_api_collection != NOT_PASSED
    raise ArgumentError, "You must pass an absolute path to rest_api_collection" unless rest_api_collection.start_with? "/"

    @rest_api_collection = rest_api_collection
  end

  @rest_api_collection
end

#rest_api_document(rest_api_document = NOT_PASSED, first_element_only: false) ⇒ String

Define the REST API document URL with RFC 6570 template support

Sets the URL pattern for individual resource documents. The URL can include RFC 6570 URI templates that will be expanded using property values. This URL is used for:

  • GET requests to retrieve a specific resource
  • PATCH/PUT requests to update a resource
  • DELETE requests to remove a resource

Examples:

Path-based URL

rest_api_document '/api/v1/users/{username}'
# With username='john':
# GET    /api/v1/users/john
# PATCH  /api/v1/users/john
# DELETE /api/v1/users/john

Query-based URL

rest_api_document '/api/v1/users?name={username}&email={email}'
# With username='john', email='[email protected]':
# GET /api/v1/users?name=john&[email protected]

With first_element_only

rest_api_document '/api/v1/users?name={username}', first_element_only: true
# API returns: [{"name": "john", ...}]
# Resource sees: {"name": "john", ...}

Raises:

  • (ArgumentError) —

    If the path doesn't start with '/'

See Also:



133
134
135
136
137
138
139
140
141
 
# File 'lib/chef/dsl/rest_resource.rb', line 133

def rest_api_document(rest_api_document = NOT_PASSED, first_element_only: false)
  if rest_api_document != NOT_PASSED
    raise ArgumentError, "You must pass an absolute path to rest_api_document" unless rest_api_document.start_with? "/"

    @rest_api_document = rest_api_document
    @rest_api_document_first_element_only = first_element_only
  end
  @rest_api_document
end

#rest_api_document_first_element_only(rest_api_document_first_element_only = NOT_PASSED) ⇒ Object 



228
229
230
231
232
233
 
# File 'lib/chef/dsl/rest_resource.rb', line 228

def rest_api_document_first_element_only(rest_api_document_first_element_only = NOT_PASSED)
  if rest_api_document_first_element_only != NOT_PASSED
    @rest_api_document_first_element_only = rest_api_document_first_element_only
  end
  @rest_api_document_first_element_only
end

#rest_identity_map(rest_identity_map = NOT_PASSED) ⇒ Hash?

Define explicit identity mapping for resource identification

Explicitly specifies which JSON fields and resource properties uniquely identify a resource. Use this when automatic identity inference from the document URL is insufficient or when dealing with composite keys.

If not specified, the identity is automatically inferred from RFC 6570 templates in the document URL.

Examples:

Simple identity

property :username, String, identity: true
rest_identity_map({ 'username' => :username })

Composite identity

property :name, String
property :namespace, String

rest_identity_map({
  'name' => :name,
  'namespace' => :namespace
})

Nested identity fields

property :user_id, String
property :org_id, String

rest_identity_map({
  'user.id' => :user_id,
  'organization.id' => :org_id
})



179
180
181
182
 
# File 'lib/chef/dsl/rest_resource.rb', line 179

def rest_identity_map(rest_identity_map = NOT_PASSED)
  @rest_identity_map = rest_identity_map if rest_identity_map != NOT_PASSED
  @rest_identity_map
end

#rest_post_only_properties(rest_post_only_properties = NOT_PASSED) ⇒ Array<Symbol>

Declare properties that should only be sent during resource creation

Specifies which properties should only be included in POST (create) requests and excluded from PATCH/PUT (update) requests. This is useful for properties that can only be set during initial creation or would cause errors if included in updates.

Examples:

Single property

property :password, String, sensitive: true
property :username, String

rest_post_only_properties :password
# Password only sent when creating user, not when updating

Multiple properties

property :password, String, sensitive: true
property :initial_role, String
property :username, String

rest_post_only_properties [:password, :initial_role]

Common use cases

# Passwords that can't be updated via API
rest_post_only_properties :admin_password

# Resource size that can't be changed after creation
rest_post_only_properties :disk_size_gb

# Initialization parameters
rest_post_only_properties [:template_id, :source_snapshot]



221
222
223
224
225
226
 
# File 'lib/chef/dsl/rest_resource.rb', line 221

def rest_post_only_properties(rest_post_only_properties = NOT_PASSED)
  if rest_post_only_properties != NOT_PASSED
    @rest_post_only_properties = Array(rest_post_only_properties).map(&:to_sym)
  end
  @rest_post_only_properties || []
end

#rest_property_map(rest_property_map = NOT_PASSED) ⇒ Hash

Define property mapping between resource properties and JSON API fields

Maps resource properties to their corresponding locations in the JSON API payload. Supports both simple 1:1 mappings and complex transformations.

Examples:

Simple 1:1 mapping

rest_property_map [:username, :email, :role]
# Equivalent to: { username: 'username', email: 'email', role: 'role' }

Nested JSON paths

rest_property_map({
  username: 'user.name',
  email: 'user.contact.email',
  role: 'permissions.role'
})

Custom mapping functions

rest_property_map({
  username: 'username',
  tags: :tags_mapping  # Calls tags_from_json and tags_to_json methods
})

See Also:

  • Method that uses this mapping to extract values
  • Method that uses this mapping to create JSON


58
59
60
61
62
63
64
65
 
# File 'lib/chef/dsl/rest_resource.rb', line 58

def rest_property_map(rest_property_map = NOT_PASSED)
  if rest_property_map != NOT_PASSED
    rest_property_map = rest_property_map.to_h { |k| [k.to_sym, k] } if rest_property_map.is_a? Array

    @rest_property_map = rest_property_map
  end
  @rest_property_map
end