DelphiDabbler SWAG Archive
REST API Documentation

Introduction

The implementation of the SWAG (SourceWare Archive Group) archive hosted on DelphiDabbler.com can be accessed via a read-only REST API. This documentation describes how to use the API.

The API is accessed using HTTP GET commands with URIs in the form:

http://swag.delphidabbler.com/api/api_version/resource?query_string

where api_version is the version of the API being used, resource is the resource being requested and query_string is a query string containing additional information. Each of these is discussed in detail below.

Responses to API calls are always sent in UTF-8 encoded text in either JSON, JSONP or XML format.

Errors are signalled by the HTTP response code and via a code in the response text.

API Version

At present the only supported version is version 1 and this must be specified in all API calls. The version number is represented in URIs as v1.

Example:

http://swag.delphidabbler.com/api/v1/categories

Query Strings

Query strings are comprised of parameters in name=value format, separated by commas. Parameter names and values must be URL encoded, with spaces represented by '+' characters.

There are two kinds of parameters, common parameters and command specific parameters. The former can be used with any API call and are described below. The latter have meaning only for some resources. They are described in the relevant resources section.

Common Parameters

The following common parameters are supported:

suppressResponseCodes
Determines whether errors are signalled using the HTTP response code or not. A false value means that HTTP response codes are used to signal an error while true means that HTTP code 200 is always used and errors are signalled as part of the returned text (see below).
Valid values are true or false.
Default: false.
format
Specifies the format required for responses.
Valid values are:
json
The response is in JSON format.
jsonp
The response is in JSONP format. The name of the callback function used in the response is swagApiCallback by default. This can be changed via the jsonCallback parameter (see below).
xml
The response is in XML format.
Default: json
jsonCallback
Specifies the name of the callback function used in JSONP responses. This parameter is ignored is the format response is not jsonp.
A valid JavaScript function name must be specified.
Default: swagApiCallback

Response Format

Every resource request returns a response in a standardised format. Every response has common elements and resource specific elements.

The common elements are discussed here while resource specific elements are discussed in the appropriate resource section below.

Every response has an element named status. The value of this element is either ok or error. Pretty obviously these value represent successful and error responses respectively. The format of the remainder of the response depends on the value of the status element.

Successful Responses

A succsessful response has just one further common element named command. The value of this element is simply the command component of the requested resource (see below). For example for the categories resource, the value of command is categories.

There will be one further top-level element whose name depends on the resource. This element will contain all the information returned by the resource itself.

Error Responses

Error responses have the same format for all requests. There is a single error element containing the following sub-elements:

status
Error status code. This is the same as the HTTP response code that will have been used for the error unless the suppressResponseCodes parameter has been set to true. This value is provided for use in cases where the error HTTP response codes have been suppressed to find out what the code would have been had it not been suppressed.
code
The API error code that provides more detailed information about the error. Supported values are:
1
Unexpected error.
2
No resource was requested.
3
A badly formatted or no API version was specified.
11
The specified API version is not supported.
12
The specified API command was not recognised.
13
The requested API resource was incorrectly constructed, i.e. it has missing, unexpected or invalid components.
14
A parameter in the query string has an invalid or non-existant value.
21
An invalid request was made of the SWAG database.
22
There was an error in accessing the SWAG database: this is a server failure.
All error codes give an HTTP 400 error except code 22 which results in an HTTP 500 error.
message
A message the describes the error.
command
The API command that caused the error. Where the error relates to a missing or invalid command this value may be empty or refer to an invalid command.

Format Specific Information

JSON

Each element of a response is either a named JSON object, array or simple value.

XML

Every XML response is enclosed in top-level tags. <response> ... </response> that contain all other response elements.

Every element of the response is either a compound XML tag containing other elements or is a simple tag containing the related data as PCDATA.

Resources

Required resources are specified by the path that follows the api_version component of the URI. The resource path is in the form command/additional_data where the /additional_data part may not be present or permitted for some resources.

Additional information may be be provided as part of the query string.

In version 1 of the API the following commands are available:

categories Command

Returns a list of all available SWAG categories. The ID and title of each category are provided.

Resource path

categories

Parameters

There are no command specific parameters.

Response format

The returned information is contained in a single categories element. categories contains an id and a title element for each category in the database, giving the category's unique ID and descriptive title respectively.

In JSON format categories is an array containing an object for every category, each of which has id and title string values.

In XML categories is a compound tag containing a category sub-tag for every category, each of which has id and title sub-tags.

Examples

Example URL:

http://swag.delphidabbler.com/api/v1/categories

Example responses:

JSON:

{
  "status":"ok",
  "command":"categories",
  "categories":[
    {
      "id":"ANSI",
      "title":"ANSI Control & Ouput"
    },
    {
      "id":"ARCHIVES",
      "title":"Archive Handling"
    },

    ... more category elements ...

  ]
}

XML:

<response>
  <status>ok</status>
  <command>categories</command>
  <categories>
    <category>
      <id>ANSI</id>
      <title>ANSI Control & Ouput</title>
    </category>
    <category>
      <id>ARCHIVES</id>
      <title>Archive Handling</title>
    </category>

    ... more category tags ...

  </categories>
</response>

snippet Command

Returns information about a single snippet.

Resource path

snippet/snippet_id

snippet_id is an integer that uniquely identifies the snippet in the database. The snippets command can be used to retrieve valid snippet IDs.

Parameters

The command supports the following optional parameter:

fields
Specifies the snippet fields (or properties) that are to be returned for the requested snippet. The required fields are specified as a comma delimited list, with no spaces.
Valid fields are:
id
Unique ID of the snippet as an integer.
category
ID string of the category containing the snippet.
file_name
The snippet's file name within the related category folder in the original SWAG database.
datestamp
Date and time the snippet was created or last updated. This value is a string in SQL date format (i.e. YYYY-MM-DD hh:mm:ss).
title
The snippet's descriptive title.
author
Name of the snippet's author.
source_code
The snippet's source code. In the case of snippets that are documents rather than Pascal code, this field contains the document text.
is_document
Integer value that indicates in the snippet contains document document text (1) or source code (0).
The default value for this parameter is id,title,author

Response format

The returned field values are contained in single element named snippet. This element contains a sub-element for each requested field. The field elements have same name as the corresponding field (see the fields parameter above).

In JSON snippet is an object with values for each requested field. The values have the same type as the fields listed in the documentation of the fields parameter.

In XML format snippet is a compound tag containing a sub-tags for each requested field.

Examples

Example URL

http://swag.delphidabbler.com/api/v1/snippet/470?fields=title,source_code

Example resonses:

JSON

{
  "status":"ok",
  "command":"snippet",
  "snippet":{
    "title":"How to copy files in Delphi",
    "source_code":"\r\n{This way uses a File stream.}\r\nProcedure ..."
  }
}

XML

<response>
  <status>ok</status>
  <command>snippet</command>
  <snippet>
    <title>How to copy files in Delphi</title>
    <source_code>
      {This way uses a File stream.}
      Procedure FileCopy( Const sourcefilename, targetfilename: String );
      ...
    </source_code>
  </snippet>
</response>

snippet-count Command

Returns the number of snippets in a given category or in the whole database.

Resource path

snippet-count/category_id

or

snippet-count/*

category_id is the ID string of the required category. If the all snippets in the database are to be counted then then use * in place of the category ID. Valid category IDs can be found using the categories command.

Parameters

There are no command specific parameters.

Response format

The returned value is just a single element name snippetCount whose value is the required number of snippets.

In JSON this is simply an integer value named snippetCount.

In XML there is a single snippetCount tag containing the required count as a string.

Examples

Example URL:

http://swag.delphidabbler.com/api/v1/snippet-count/delphi

Example responses

JSON

{
  "status":"ok",
  "command":"snippet-count",
  "snippetCount":467
}

XML

<response>
  <status>ok</status>
  <command>snippet-count</command>
  <snippetCount>467</snippetCount>
</response>

snippets Command

Returns details about each snippet in a given category or in the whole database.

Resource path

snippets/category_id

or

snippets/*

category_id is the ID string of the required category. If the all snippets in the database are to be returned then use * as the category ID. Valid category IDs can be found using the categories command.

Parameters

The command supports the following optional parameters:

fields
Specifies the snippet fields (or properties) that are required for each snippet. The required fields are specified as a comma delimited list, with no spaces.
Valid fields are:
id
Unique ID of the snippet as an integer.
category
ID string of category containing the snippet.
file_name
Snippet's file name within the related category folder in the original SWAG database.
datestamp
Date and time the snippet was created or last updated. This value is a string in SQL date format (i.e. YYYY-MM-DD hh:mm:ss).
title
The snippet's descriptive title.
author
Name of the snippet's author.
source_code
The snippet's source code. In the case of snippets that are documents rather than Pascal code, this field contains the document text.
is_document
Integer value that indicates in the snippet contains document document text (1) or source code (0).
The default value for this parameter is id,title,author
limit
Limits the number of snippets returned by a request.
limit takes a value that is two non-negative integers, separated by a comma. The first number is the offset into the result set of the first snippet to be returned and the second number is the number of snippets to be included. Offsets are zero based so that an offset of 0 gets the first result.
Using an offset that falls beyond the last snippet in the result set causes an empty result set to be returned. If the number of snippets specified exceeds the number available then all available snippets from the offset are returned.
A common use for for limit is to walk through result sets in managable chunks so that you don't return too much data in a single request. For example, if there are 107 snippets in the requested category and you want to read them 20 at a time make repeated requests starting with limit=0,20 and incrementing the offset by 20 on each request until the result set is empty.

Response format

All the returned snippets are contained in the single snippets element. This element contains an entry for each snippet that in turn has an element for each requested field. The field elements have same name as the corresponding field (see the fields parameter above).

In JSON format snippets is an array with an element for every snippet. These objects have values for each requested field. The values have the same type as the fields listed in the documentation of the fields parameter. In cases where no snippets are returned, the snippets array is empty.

In XML format snippets is a compound tag containing a snippet sub-tag for every snippet. The snippet tags have sub-tags for each requested field. In cases where no snippets are returned the snippets tag is empty.

Examples

Example URL:

http://swag.delphidabbler.com/api/v1/snippets/delphi?fields=id,title,datestamp&limit=24,4

Example responses:

JSON

{
  "status":"ok",
  "command":"snippets",
  "snippets":[
    {
      "id":491,
      "title":"Getting the Line number in a memo Field",
      "datestamp":"1995-11-22 13:33:00"
    },
    {
      "id":492,
      "title":"Capturing the Desktop to a form",
      "datestamp":"1995-11-22 13:33:00"
    },
    {
      "id":493,
      "title":"File Copying in DELPHI",
      "datestamp":"1995-11-22 15:49:00"
    },{
      "id":494,
      "title":"File Manager Drag\/Drop",
      "datestamp":"1995-11-22 15:49:00"
    }
  ]
}

XML

<response>
  <status>ok</status>
  <command>snippets</command>
  <snippets>
    <snippet>
      <id>491</id>
      <title>Getting the Line number in a memo Field</title>
      <datestamp>1995-11-22 13:33:00</datestamp>
    </snippet>
    <snippet>
      <id>492</id>
      <title>Capturing the Desktop to a form</title>
      <datestamp>1995-11-22 13:33:00</datestamp>
    </snippet>
    <snippet>
      <id>493</id>
      <title>File Copying in DELPHI</title>
      <datestamp>1995-11-22 15:49:00</datestamp>
    </snippet>
    <snippet>
      <id>494</id>
      <title>File Manager Drag/Drop</title>
      <datestamp>1995-11-22 15:49:00</datestamp>
    </snippet>
  </snippets>
</response>