Codebase API Documentation

Creating Records.

If you want to create an object in Codebase, you can simply pass the object's XML definition to the appropriate URL. Throughout the API documentation, you will see 'API URL' tables which include the URL and method which should be used when talking to the API.

To create a record, you can simply send a POST request to the provided URL along with the XML in the body of the request.

If your record was added successfully, you'll receive a 201 Created HTTP response and the body will contain the object's XML block as shown on the appropriate page in this documentation.

Updating Records

To edit an existing record, you should send data to the URL defined in the appropriate API URLs table using the PUT method. This works in much the same way as creating records. Unless otherwise specified, the XML you send should be a complete representation of the object which can be retrieved using the appropriate GET method.

If your record was updated successfully, you'll receive a 200 OK HTTP response with no body.

Errors

If there is an error processing your request, you will receive a 422 Unprocessable Entity HTTP response and the body of the response will include an array of errors (see below) which need to be addressed,

Errors

<errors>
  <error>Field was invalid</error>
  <error>Another field was blank</error>
</errors>

Code Example using Ruby's net/http library

The example below shows how one would go about adding a new ticket but the same principle can be applied to any object with any URL and set of data.

Ruby API Example

require 'uri'
require 'net/http'
# Create the request, set appropriate headers
url = URI.parse("http://api3.codebasehq.com/widgets/tickets")
req = Net::HTTP::Post.new(url.path)
req.basic_auth('account/dave', '6b2579a03c2e8825a5fd0a9b4390d15571f3674d')
req.add_field('Content-type', 'application/xml')
req.add_field('Accept', 'application/xml')
# Build our XML payload
xml = "<ticket><summary>My Example Ticket</summary><status-id>1234</status-id>
<priority-id>1234</priority-id><ticket-type>bug</ticket-type></ticket>"
# Send the request 
res = Net::HTTP.new(url.host, url.port).start {|http| http.request(req, xml)}
case res
when Net::HTTPCreated
  puts "Record was created successfully."
else
  puts "An error occurred while adding this record"
end