README

What is it?

This is a small PHP client for the Netbox API REST services.

Requirements

• PHP >=8.3
• guzzlehttp/guzzle 7.10
• ocolin/global-type ^2.0

Installation

composer require ocolin/netbox

TODO

• Add an images upload function
• Integration testing for Netbox 3.

Configuration

The client can be configured in two ways. Via environment variables, and constructor arguments.

Properties

Note: Version 2 authentication takes both a key and a token, while Version 1 only uses a token.

Environment Variables

// Manually creating for demonstration
$_ENV['NETBOX_API_HOST']  = 'http://localhost:8000';
$_ENV['NETBOX_API_AUTH']  = 2;
$_ENV['NETBOX_API_TOKEN'] = 'abcdefg';
$_ENV['NETBOX_API_KEY']   = 'abcdefg';

$netbox = new \Ocolin\Netbox\Netbox();

Constructor arguments

The constructor takes a configuration object that allows you to add your configuration settings. These can also be used in conjunction with environment variables. Any missing parameters will be checked in the Environment.

$netbox = new Ocolin\Netbox\Netbox(
    config: new Ocolin\Netbox\Config(
           host: 'http://localhost:8000',
           auth: 2,
          token: 'abcdefg',
            key: 'abcdefg',
        options: [
            'verify' => true
        ] 
    )
);

Options

As can be seen in previous example, there is an options parameter. This allows you to specify Guzzle HTTP client settings if needed. This can be useful if you want to enable SSL verification, or HTTP timeout, etc. The client defaults to SSL verification off.

HTTP defaults

Response

The client outputs a response object with the following parameters:

Method functions

Path interpolation

Any {tokens} found in the endpoint path will be replaced with matching keys from the $query array. Those keys are then removed from the query string automatically.

Note: Netbox requires a trailing slash on all endpoint paths. The client adds one automatically if missing.

GET

Get a resource

$output = $netbox->get(
    endpoint: '/api/dcim/sites/{id}/',
       query: [ 'id' => 123 ]
);

POST

Create a new resource

$output = $netbox->post(
    endpoint: '/api/dcim/sites/',
    body: [
        'name' => 'My Site',
        'slug' => 'My-Site'
    ]
);

PATCH

Update a value in a resource

$output = $netbox->patch(
    endpoint: '/api/dcim/sites/{id}/',
       query: [ 'id' => 123 ],
        body: [ 'name' => 'My Updated Name' ]
);

PUT

Update/Replace an entire resource

$output = $netbox->put(
    endpoint: '/api/dcim/sites/{id}/',
       query: [ 'id' => 123 ],
        body: $newBody
);

DELETE

Delete a resource

$output = $netbox->delete(
    endpoint: '/api/dcim/sites/{id}/',
       query: [ 'id' => 123 ]
);

OPTIONS

OPTIONS returns information about an endpoint.

$output = $netbox->options( endpoint: '/api/dcim/sites/' );