Net-at-hand API Documentation

Introduction

The Net-at-hand API (application programming interface) exists to allow developers to access access and manipulate the information in their Net-at-hand account. The API gives CRUD access (create, read, update, and destroy) to clients, sites, and content.

The purpose of this documentation is not to give a tutorial for any one programming language to access the API. We are simply documenting the how the API works and the general practices for using it. Specific implentation of those practices is not covered.

All server responses are delivered in standard JSON format.

Authentication

The Net-at-hand API uses basic HTTP authentication. The authentication credentials match the email and password that you normally use to log into the Net-at-hand admin area.

Note that the api should be accessed via an encrypted SSL connection at https://net-at-hand.com/api. This is not enforced, however, at the server level, so you are able to access the API in an unencrypted fashion. If you do this, however, the username and password will be send in the clear and could be compromised by someone intercepting the transmission of the information.

Get, Post, Put, Delete

The Net-at-hand API is designed to adhere to the RESTful methodology of application design and as such relys on the standard HTTP methods of GET, POST, PUT, DELETE to manipulate the data in your account. For each URL listed in the documentation below, the allowed methods and what they perform will be listed.

A list of attributes that can be used for POST and PUT commands is given below.

Clients

/api/clients

• GET—returns a list of all the clients in your account. If you do not have a reseller account, it returns an empty array.
• POST—adds a new client to your list of clients. Note that an empty site and design are automatically generated for your client by Net-at-hand. Returns an updated list of clients.

/api/clients/clientID

• GET—returns the client with the referenced id.
• PUT—updates the supplied attributes of the client with the referenced id.
• DELETE—destroys the client with the referenced id. Note that this destroys the clients account completely which includes all the clients websites and designs.

/api/clients/clientID/sites

• GET—returns all the sites in the client’s account
• POST—adds a new site to the list of the client’s sites. Returns a list of the client’s sites.

Sites

/api/sites

• GET—returns a list of sites in your account.
• POST—adds a new site to your account. Returns an updated list of sites in your account.

/api/sites/siteID

• GET—returns the site with the referenced id.
• PUT—updates the supplied attributes of the site referenced by the id.
• DELETE—destroys the site referenced by the id.

Nodes

/api/sites/siteID/nodes

• GET—returns an array of content nodes in the main list for the site. Note that the list includes all nodes regardless of status.
• POST—adds a new content node to the main list of the site.

/api/sites/siteID/nodes/nodeID

• GET—returns the content node referenced by nodeID. Note that the node does not need to be in the main list of the website. This URL will return any node that is part of the site, regardless of the nodes hirearchical location.
• PUT—updates the supplied attributes for the content node referenced by nodeID
• DELETE—destroys the content node referenced by nodeID

/api/sites/siteID/nodes/nodeID/children

• GET—returns an array of content nodes that are children of nodeID
• POST—adds a new content node as a child of the node reference by nodeID

Attributes

When using POST or PUT commmands, attribute names must include the name of the data that you are trying to mantipulte. So the format for all three data types would be:

• client[attribute]
• site[attribute]
• node[attribute]

For example, if you wanted to update the name of a client, the attribute name would be “client[name]”.

Alternatively all the attributes can be passed as JSON with a single attribute named “json”.

Clients

• id (read only)
• name
• email

Nodes

• id (read only)
• status
• title
• tagline
• description
• keywords
• html_title
• created_at (read only)

Nodes

• id (read only)
• status
• title
• urls
• created_at (read only)
• published_at
• updated_at (read only)
• description
• keywords
• html_title
• type (read only once created)—the type determines what kind of content the node will be. Allowed values are: page, blog, post, folder, album, image, calendar, event, contactform. Nodes of type post, image, and event are only allowed in nodes of type blog, album, and calendar (respectively).
• parent_id (read only)