Skip to content

Commit

Permalink
Merge remote-tracking branch 'kylo/issue/22522-facts-api-doc'
Browse files Browse the repository at this point in the history
* kylo/issue/22522-facts-api-doc:
  (#22522) Use :nodename instead of :name in URIs
  (#22522) some formatting fixups
  (#22522) validate node facts against facts schema
  (#22522) mark the 4 fields in the facts schema as required
  (#22522) add documentation for facts endpoints
  (#22522) rename catalog_facts.json -> facts.json

Conflicts:
	api/docs/http_api_index.md

Resolved conflict in table of contents.
joshcooper committed Sep 24, 2013
2 parents 6fc103d + 3842b17 commit e632ffd
Showing 8 changed files with 183 additions and 11 deletions.
4 changes: 2 additions & 2 deletions api/docs/http_api_index.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
Services
--------

* {file:api/docs/http_resource_type.md Resource Type}
* {file:api/docs/http_certificate.md Certificate}
* {file:api/docs/http_catalog.md Catalog}
* {file:api_docs/http_facts.md Facts}
* {file:api/docs/http_file_content.md File Content}
* {file:api/docs/http_report.md Report}
* {file:api/docs/http_resource_type.md Resource Type}

To be documented:

* node
* facts
* file_metadata
* file_bucket_file
* certificate
6 changes: 3 additions & 3 deletions api/docs/http_catalog.md
Original file line number Diff line number Diff line change
@@ -8,8 +8,8 @@ Find

Retrieve a catalog.

POST /:environment/catalog/:name
GET /:environment/catalog/:name
POST /:environment/catalog/:nodename
GET /:environment/catalog/:nodename

### Supported HTTP Methods

@@ -154,6 +154,6 @@ Schema
------

In the POST request body (or the GET query), the facts parameter should adhere to the
api/schemas/catalog_facts.json schema.
api/schemas/facts.json schema.

A catalog response body should adhere to the api/schemas/catalog.json schema.
2 changes: 1 addition & 1 deletion api/docs/http_certificate.md
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ Find

Get a certificate.

GET /:environment/certificate/:name
GET /:environment/certificate/:nodename


### Supported HTTP Methods
144 changes: 144 additions & 0 deletions api/docs/http_facts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
Facts
=============

The `facts` endpoint allows getting or setting the facts for the specified node name. The `facts_search` endpoint
allows retrieving a list of node names containing the specified facts.

Find
----

Get facts for a node.

GET /:environment/facts/:nodename

### Supported HTTP Methods

GET

### Supported Format

Accept: pson, text/pson

### Parameters

None

### Example Response

* Note: list of facts was shortened for readability.
* Note: pson was formatted for readability.

#### Facts found

GET /env/facts/elmo.mydomain.com

HTTP 200 OK
Content-Type: text/pson

{
"name": "elmo.mydomain.com",
"values": {
"architecture": "x86_64",
"kernel": "Darwin",
"domain": "local",
"macaddress": "70:11:24:8c:33:a9",
"osfamily": "Darwin",
"operatingsystem": "Darwin",
"facterversion": "1.7.2",
"fqdn": "elmo.mydomain.com",
},
"timestamp": "2013-09-09 15:49:27 -0700",
"expiration": "2013-09-09 16:19:27 -0700"
}

Save
----

Store facts for a node. The request body should contain pson-formatted facts.

PUT /:environment/facts/:nodename

### Supported HTTP Methods

PUT

### Supported Format

Accept: pson, text/pson

### Parameters

None

### Example Response

* Note: list of facts was shortened for readability.
* Note: pson was formatted for readability.

#### Facts found

PUT /env/facts/elmo.mydomain.com

Content-Type: text/pson

{
"name": "elmo.mydomain.com",
"values": {
"architecture": "x86_64",
"kernel": "Darwin",
"domain": "local",
"macaddress": "70:11:24:8c:33:a9",
"osfamily": "Darwin",
"operatingsystem": "Darwin",
"facterversion": "1.7.2",
"fqdn": "elmo.mydomain.com",
},
"timestamp": "2013-09-09 15:49:27 -0700",
"expiration": "2013-09-09 16:19:27 -0700"
}

HTTP/1.1 200 OK
Content-Type: text/pson

"/etc/puppet/var/yaml/facts/joebob.local.yaml"

Search
----

Get the list of nodes matching the facts_search parameters

GET /:environment/facts_search/search

### Supported HTTP Methods

GET

### Supported Format

Accept: pson, text/pson

### Parameters

For the parameters, see http://docs.puppetlabs.com/guides/rest_api.html#facts-search.

### Response

The response is an array of node names. The array is square-bracket delimited; the node names are quoted and
comma separated.

### Example Response

#### Facts found

GET /env/facts_search/search?facts.processorcount.ge=2

HTTP 200 OK
Content-Type: text/pson

["elmo.mydomain.com","kermit.mydomain.com"]

Schema
------

The representation of facts, whether returned from a GET or contained in a PUT body, should adhere to the
api/schemas/facts.json schema.
2 changes: 1 addition & 1 deletion api/docs/http_resource_type.md
Original file line number Diff line number Diff line change
@@ -25,7 +25,7 @@ Find
Get info about a specific class, defined type, or node, by name. Returns a
single resource_type response object (see "Schema" below).

GET /:environment/resource_type/:name
GET /:environment/resource_type/:nodename

> **Note:** Although no two classes or defined types may have the same name,
> it's possible for a node definition to have the same name as a class or
1 change: 1 addition & 0 deletions api/schemas/catalog_facts.json → api/schemas/facts.json
Original file line number Diff line number Diff line change
@@ -24,5 +24,6 @@
"type": "string"
}
},
"required": ["name", "values", "timestamp", "expiration"],
"additionalProperties": false
}
6 changes: 3 additions & 3 deletions spec/unit/configurer/fact_handler_spec.rb
Original file line number Diff line number Diff line change
@@ -9,11 +9,11 @@
require 'json-schema'

JSON_META_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/json-meta-schema.json')))
CATALOG_FACTS_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/catalog_facts.json')))
FACTS_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/facts.json')))

describe "catalog facts schema" do
it "should validate against the json meta-schema" do
JSON::Validator.validate!(JSON_META_SCHEMA, CATALOG_FACTS_SCHEMA)
JSON::Validator.validate!(JSON_META_SCHEMA, FACTS_SCHEMA)
end
end

@@ -92,7 +92,7 @@ def reload_facter
end

def validate_as_json(catalog_facts)
JSON::Validator.validate!(CATALOG_FACTS_SCHEMA, catalog_facts)
JSON::Validator.validate!(FACTS_SCHEMA, catalog_facts)
end

it "should generate valid facts data against the facts schema", :unless => Puppet.features.microsoft_windows? do
29 changes: 28 additions & 1 deletion spec/unit/node/facts_spec.rb
Original file line number Diff line number Diff line change
@@ -1,8 +1,23 @@
#! /usr/bin/env ruby
require 'spec_helper'
require 'matchers/json'
require 'puppet/node/facts'

# the json-schema gem doesn't support windows
if not Puppet.features.microsoft_windows?
require 'json'
require 'json-schema'

JSON_META_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/json-meta-schema.json')))
FACTS_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/facts.json')))

describe "catalog facts schema" do
it "should validate against the json meta-schema" do
JSON::Validator.validate!(JSON_META_SCHEMA, FACTS_SCHEMA)
end
end

end

describe Puppet::Node::Facts, "when indirecting" do
before do
@facts = Puppet::Node::Facts.new("me")
@@ -147,6 +162,18 @@
result['expiration'].should == facts.expiration.to_s
end

def validate_as_json(facts)
JSON::Validator.validate!(FACTS_SCHEMA, facts)
end

it "should generate valid facts data against the facts schema", :unless => Puppet.features.microsoft_windows? do
Time.stubs(:now).returns(@timestamp)
facts = Puppet::Node::Facts.new("foo", {'a' => 1, 'b' => 2, 'c' => 3})
facts.expiration = @expiration

validate_as_json(facts.to_pson)
end

it "should not include nil values" do
facts = Puppet::Node::Facts.new("foo", {'a' => 1, 'b' => 2, 'c' => 3})
pson = PSON.parse(facts.to_pson)

0 comments on commit e632ffd

Please sign in to comment.