:

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="description" content=""> <meta name="author" content=""> <link rel="icon" href="../../favicon.ico"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <script src='/js/jquery.wiggle.min.js' type='text/javascript'></script> <script src="/js/explorer.js" type="text/javascript"></script> <link href="/css/xcode.css" type="text/css" media="screen" rel="stylesheet"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" integrity="sha384-1q8mTJOASx8j1Au+a5WDVnPi2lkFfwwEAa8hDDdjZlpLegxhjVME1fgjWPGmkzs7" crossorigin="anonymous"> <link href="/css/style.css" rel="stylesheet"> <link href="/css/govstrap.css" rel="stylesheet"> <link href="/css/govstrap_extra.css" rel="stylesheet"> <link href="/css/developer.css" rel="stylesheet"> <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,600" rel="stylesheet"> <link href='https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css' rel='stylesheet' type='text/css'>  <script src='/js/highlight.pack.js' type='text/javascript'></script> <script>hljs.initHighlightingOnLoad();</script> <title>: </title> </head> <body > <nav class="navbar navbar-fixed-top shadow"> <div class="container-fluid"> <div class="row"> <div class="1 col-lg-1 hidden-xs hidden-sm hidden-md"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10"> <div class="navbar-header"> <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/">Companies House</a> </div> <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> <ul class="nav navbar-nav navbar-right"> <li> <a href="/">All APIs</a> </li> </ul> </div> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> </nav> <div class="container-fluid"> <div class="row"> <div class="hidden-md col-lg-1 hidden-xs hidden-sm"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10 main-body"> <div class="body-header body-header-content"> <ul id="SIN" class="nav navbar-nav navbar-right userbar deactivate"> <li> <span class="user_info" id="email"></span>: </li> <li><a href="/developer/applications">Applications</a></li> <li> <a href="/developer/signout">Sign out</a> </li> </ul> <ul id="SOUT" class="nav navbar-nav navbar-right userbar deactivate"> <li><a href="/developer/signin">Sign in</a></li> </ul> <ul id="ERROR" class="nav navbar-nav navbar-right userbar deactivate"> <li id="placeholder"></li> </ul> </div> <div class="row"> <div class="col-xs-12 col-sm-3 col-md-3 col-lg-3"> <script> $(document).ready(function(){ $('.items').hide(); var $pagename=decodeURI( window.location.pathname ); var $parent=$('ul[id="navigation"]'); var $element=$parent.find('a[href$="'+$pagename+'"]'); if( $element.length == 0 ) { $pagename = sessionStorage.lastpage; $element=$parent.find('a[href$="'+$pagename+'"]'); } sessionStorage.lastpage = $pagename; var api_id = $element.data('outer'); var toggler = $("#toggle"+api_id); var outerul = $("#ul"+api_id); outerul.addClass('in'); toggler.addClass('open'); toggler.removeClass('collapsed'); $element.addClass('nav-selected'); $parent.removeClass('hide'); }); </script> <div class="side-nav affix"> <ul class="nav nav-sidebar hide" id="navigation"> <li> <a href="/guides/index">Companies House API</a> </li> <li> <a href="/guides/gettingStarted">Getting started</a> </li> <li> <a href="/guides/quickStart">Quick start</a> </li> <li> <a href="/guides/introduction">Introduction</a> </li> <li> <a href="/guides/authorisation">Authorisation</a> </li> <li> <a href="/guides/developerGuidelines">Developer guidelines</a> </li> <li> <a href="/guides/rateLimiting">Rate limiting</a> </li> <li> <a href="/guides/versioning">API versioning</a> </li> </ul> </div> </div> <div class="col-xs-12 col-sm-9 col-md-9 col-lg-9 main"> <h1 class="page-header"><a name="introduction-to-the-companies-house-json-api" class="anchor" href="#introduction-to-the-companies-house-json-api" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>Introduction to the Companies House JSON API</h1> <p>The Companies House API is a REST API that provides a simple, consistent approach to requesting and modifying data. REST stands for <a href="http://en.wikipedia.org/wiki/Representational_state_transfer" rel="nofollow">Representational State Transfer</a>, an architectural software style in which standard HTTP request methods are used to retrieve and modify representations of data. This is identical to the process of retrieving a web page, or submitting a web form.</p> <p>Previous versions of the Companies House API implemented an XML-RPC style of interface. Here data is retrieved or submitted by POSTing XML documents to the service, each defining the method to be called and the data to be processed.</p> <p>The difference between both API approaches is defined below.</p> <h2 class="sub-header"><a name="xml-rpc-soap" class="anchor" href="#xml-rpc-soap" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> XML-RPC / SOAP</h2> <p>An XML-RPC or or SOAP API might provide four methods to manipulate a customer record:</p> <pre><code><code>http://api.example.domain/createCustomer http://api.example.domain/deleteCustomer http://api.example.domain/updateCustomer http://api.example.domain/getCustomer </code></code></pre> <p>Thus, each method defines an action that can be carried out on an entity of a particular type, in this case a customer. As an XML-RPC API, each method accepts or returns an XML document representing the customer.</p> <p>The HTTP request that would be sent by the client when calling the getCustomer method is (note that such requests must be made through a HTTP <code>POST</code>, as a GET cannot contain a message body):</p> <pre><code><code>POST http://api.example.domain/getCustomer HTTP/1.1 Content-Type: text/xml <Request> <CustomerNumber>12345</CustomerNumber> </Request> </code></code></pre> <p>The XML document submitted to the method provides the <code>customerNumber</code> of the customer record being requested.</p> <p>A common alternative calling mechanism is to provide the method name inside the XML request document. In this case, request documents are sent to a single URL, as is the case with the previous Companies House XML API:</p> <pre><code><code>POST http://api.example.domain/Gateway HTTP/1.1 Content-Type: text/xml <Request> <Method>getCustomer</Method> <Data> <CustomerNumber>12345</CustomerNumber> </Data> </Request> </code></code></pre> <p>There are several problem with such APIs. First, even though HTTP is frequently used as the transport protocol for such APIs, they cannot take advantage of existing internet infrastructure, such as HTTP caches, gateway routing or proxies. This is primarily due to the lack of <code>GET</code> request use, and/or having a single URL for multiple methods on a resource. Second, such APIs require designers to define new, application specific operations (methods) for each resource.</p> <h2 class="sub-header"><a name="representational-state-transfer" class="anchor" href="#representational-state-transfer" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a> Representational State Transfer</h2> <p>REST differs from previous approaches to API design, such as XML-RPC and SOAP which expose object methods, by directly exposing data resources. Each resource is explicitly addressed through its own URI, and can be accessed using nothing more than a standard HTTP request.</p> <p>HTTP verbs such as <code>POST</code>, <code>GET</code>, <code>PUT</code> and <code>DELETE</code> are used to retrieve and modify resources at these URIs, and operate by passing resource representations between the client and the server.</p> <p>In contrast to the above XML-RPC examples, the equivalent RESTful API request for a customer record would be:</p> <pre><code><code>GET http://api.example.domain/customer/12345 HTTP/1.1 </code></code></pre> <p>Note that the resource request is made using the <code>GET</code> method, and that there is no request body.</p> <p>In a RESTful API, a resource is modified by <code>POST</code>ing a revised resource representation, in this case JSON, to the same resource URL:</p> <pre><code><code>POST http://api.example.domain/customer/12345 HTTP/1.1 Content-Type: text/json { "CustomerName": "Joe Bloggs", "Address" : "", "etc" : "etc" } </code></code></pre> <p>Similarly, a resource may be deleted by sending a <code>DELETE</code> request to the resource URL:</p> <pre><code><code>DELETE http://api.example.domain/customer/12345 HTTP/1.1 </code></code></pre> <p>Thus REST uses the existing features of the HTTP protocol, and does not permit the designer to define application specific operations. In addition, because each resource has a globally unique URI and is able to make use of the <code>GET</code> method for resource requests, such APIs benefit from existing network components such as caches, proxies and intelligent routing.</p> <p>The <a href="/guides/index" rel="nofollow">Companies House RESTful API</a> page provides an overview of the Companies House API.</p> </div> </div> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> <div id="footer" class="footer"> <div class="container-fluid"> <div class="row"> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> <div class="col-xs-12 col-sm-12 col-md-12 col-lg-10"> <ul class="nav navbar-nav"> <li><a href="http://www.companieshouse.gov.uk/legal/termsAndConditions.shtml">Policies</a></li> <li><a href="https://find-and-update.company-information.service.gov.uk/help/cookies">Cookies</a></li> <li><a href="http://forum.aws.chdev.org">Forum</a></li> <li><a href="https://find-and-update.company-information.service.gov.uk/help/contact-us">Contact us</a></li> </ul> </div> <div class="col-lg-1 hidden-xs hidden-sm hidden-md"></div> </div> </div> </div> <script src="/js/userbar.js"></script> <script> $(document).ready(function(){ apiExplorer.setBeforeSendCallback( function( request ) { var apiKey = apiExplorer.readApiKey(); var accessToken = apiExplorer.readAccessToken(); var basicAuth = apiExplorer.getBasicAuthentication(); if( accessToken != "" ) { request.headers = {Authorization: "Bearer "+accessToken}; } else if( apiKey != "" ) { request.params = {key: apiKey}; } else if( basicAuth != "" ) { request.headers = {Authorization: "Basic "+basicAuth}; } }); }); </script> </body> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js" integrity="sha384-0mSbJDEHialfmuBBQP6A4Qrprq5OVfW37PRR3j5ELqxss1yVqOtnepnHVP9aJ7xS" crossorigin="anonymous"></script> </html>

CINXE.COM

: