This is the final, and main, api for the system (cf the AJAXie get_xxx and the list functions.) Currently at http://devel.edina.ac.uk:1201/cgi/api5 this is the API that the front-page of OpenDepot.org uses, and is expected to be the primary contact point for other developers.

Data returns

All APIs return data in the same ways:

1. You can specify the format either with the Accepts header in the http request, or with the format parameter. The options are ‘json’, ‘xml’, or ‘text’, with ‘json being the default if nothing is specified.
   • If there’s a callback parameter, and the format is json, then a crossDomain package is returned… very useful!
2. All return the data as a nested object, with three top-level elements:

    {
      'message' => {}
      'status'  => 'ok',
      'to'      => 'http://.....'
    }

   status is “ok” or “fail”, to is the url that made the query, and message contains the actual data being returned.

The call

The “locus” for the api search can be defined in a number of ways:

1. You can specify an IP number to base the search on (ip=129.215)
   • If a full quad is not given, then the full range based on what is given is assumed (so 129.215 means 129.215.0.0 to 129.215.255.255)
   • If a range is defined (ie 129.214-129.217) then the upper and lower bands are set accordingly (ie 129.214.0.0-129.217.255.255)
2. You can specify a geographic location to base the search on (geo=55.95,-3)
   • The accuracy for the search depends on the numbers given: the range is always +/- 1 either side of the last decimal place given (so a bounding box of 55.94,-2.9 to 55.96,-3.1)
3. You can specifically define an organisation ID to fix your search on (org=2736)

You can specify multiple locus points, however how they interact needs to be made clear:

• Every locus definition within the same typeis cumulative: if you specify two IP ranges, then anything in either range is listed
  • This can lead to lots and lots of results
• Every locus definition that combines different typesresults in an intersection of the results (all the results on a specified network range that are also within a specified geographic location)
  • This can lead to Zero results

In addition to defining the locus for the search, the repositories returned can be tuned to return only those of a certain type, and/or only those that accept particular types of deposits.

• type is the parameter that defines the type of repository (Institutional, Data, etc), and its the code number you need (see the appropriate list/type call for the known list of types
• content is the parameter that defines the type of content the repository accepts (pre-prints, data, learning objects, etc), and its the code number you need  (see the appropriate list/content call for the known list of content-types

The return

The data object returned is a set of net objects (indexed by net_id), within which is a list of org objects associated with that network. Within each org object is a list of repo objects. All objects conform to the specification here.

 {
   'message' => {net} => 'i38647' => { 'dec_lower' => '152.78.0.0',
                                       'dec_upper' => '152.78.255.255',
                                       'orgs' => [ { 'org_name' => 'AgentLink.org',
                                                     'org_url' => 'http://www.agentlink.org',
                                                     'repos' => [ { 'repo_name' => 'xxxxxxx',
                                                                    'org_url'   => 'yyyyyy',
                                                                    ................
                                                                   },
                                                                   {
                                                                    .................
                                                                   } ]
                                                     },
                                                     {
                                                 } ],
                                       ...........
                                     }
                      => 'i39677' => {
                                       .............
                                     }
 }

The data is not sorted before being returned.