Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

2279 lines (1864 sloc) 65.966 kb

Argumenta API

Overview / Routes / Resources / Usage / Changes

Overview

The Argumenta API provides a RESTful interface to data in JSON form.

It can be used to access resources including Users, Repos, Arguments, Propositions, and Tags.
Search, Comments, and Discussions are now also available. Planned resources include Follows and Activity.
The current version (0.1.5) provides the following features:

  • Read access for general use by unauthenticated clients.
  • Cookie-based authenticated sessions for account creation, login, and publishing.
  • JSON and JSONP response formats via the extensions '.json' and '.jsonp'.

Routes

Users

GET /users/:user.json Get a user's account info.
GET /:user.json Get a user's account and argument repos.

Repos

GET /:user/:repo.json Get a repo owned by a user.

Arguments

GET /arguments/:sha1.json Get an argument by its sha1.
GET /arguments/:sha1/propositions.json Get an argument's propositions.
GET /arguments/:sha1/discussions.json Get an argument's discussions.

Propositions

GET /propositions/:sha1.json Get a proposition by its sha1.
GET /propositions/:sha1/tags.json Get a proposition's tags.
GET /propositions/:sha1/tags-plus-sources.json Get a proposition's tags (plus source objects).

Tags

GET /tags/:sha1.json Get a tag by its sha1.

Discussions

GET /discussions/:id.json Get a discussion by id.

Comments

GET /comments/:id.json Get a comment by id.

Search

GET /search.json Search for users, arguments, and propositions.
GET /search/:query.json Search for users, arguments, and propositions.

Session Routes (Authenticated)

Join

POST /users.json Create a new user account.

Login

POST /login.json Start an authenticated user session.
GET /logout.json End the current user session.

Publish

POST /arguments.json Create a new argument (with repo).
POST /propositions.json Create a new proposition.
POST /tags.json Create a new tag (support, dispute, citation, or commentary).
POST /discussions.json Create a new discussion, with initial comment.
POST /comments.json Create a new comment, for an existing discussion.

Delete

DELETE /:name/:repo.json Delete a repo.

Resources

User

user: {
  username:    [String]
  join_date:   [String]
  gravatar_id: [String]
  metadata:    [UserMetadata]
  repos:       [Array<Repo>]    // Optional
}

UserMetadata

metadata: {
  repos_count: [Number]
}

Repo

username: [String]
reponame: [String]
user:     [User]
commit:   [Commit]
target:   [Argument]

Commit

commit: {
  object_type:  [String]
  sha1:         [String]
  target_type:  [String]
  target_sha1:  [String]
  committer:    [String]
  commit_date:  [String]
  parent_sha1s: [Array<String>]
  host:         [String]
}

Argument

argument: {
  title:        [String]
  premises:     [Array<String>]
  conclusion:   [String]
  object_type:  [String]
  sha1:         [String]
  repo:         [String]
  commit:       [Commit]             // Optional
  propositions: [Array<Proposition>] // Optional
}

Proposition

proposition: {
  text:        [String]
  object_type: [String]
  sha1:        [String]
  metadata:    [PropositionMetadata]
}

PropositionMetadata

metadata: {
  tag_sha1s: {
    support:  [Array<String>]
    dispute:  [Array<String>]
    citation: [Array<String>]
  }
  tag_counts: {
    support:  [Number]
    dispute:  [Number]
    citation: [Number]
  }
}

Tag

SupportTag, DisputeTag

tag: {
  object_type: [String]
  tag_type:    [String]
  target_type: [String]
  target_sha1: [String]
  source_type: [String]
  source_sha1: [String]
}

CitationTag

tag: {
  object_type:   [String]
  tag_type:      [String]
  target_type:   [String]
  target_sha1:   [String]
  citation_text: [String]
}

Discussion

discussion: {
  discussion_id: [Number]
  target_type:   [String]
  target_sha1:   [String]
  target_owner:  [String]
  creator:       [String]
  created_at:    [String]            // ISO 8601
  updated_at:    [String]            // ISO 8601
  comments:      [Array<Comment>]
}

Comment

comment: {
  comment_id:     [Number]
  author:         [String]
  comment_text:   [String]
  comment_date:   [String]          // ISO 8601
  discussion_id:  [Number]
}

Search

results: {
  users:        [Array<User>]
  arguments:    [Array<Argument>]
  propositions: [Array<Proposition>]
  tags:         [Array<Tag>]         // PLANNED
}

Usage

1. Errors

On error, Argumenta returns one of the following HTTP status codes:

  • 400 (Bad Request)
  • 401 (Unauthorized)
  • 404 (Not Found)
  • 409 (Resource Conflict)
  • 500 (Internal Server Error)

Also, the JSON should contain an "error" property with a message describing the problem.

2. JSONP

Each resource is available as json or jsonp. To make a JSONP request, use the extension .jsonp.

Example: JSONP Request

Here, we access the user tester, replacing the regular .json extension with .jsonp:

curl -i 'http://localhost:3000/users/tester.jsonp'

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: text/javascript
Content-Length: 253
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

jsonpCallback({
  "user": {
    "username": "tester",
    "join_date": "2013-12-02T20:41:56.735Z",
    "gravatar_id": "cf3321b32988beb65273932bf8de619e",
    "metadata": {
      "username": "tester",
      "repos_count": 1
    }
  },
  "error": null
});

Note the response is padded with a call to our default callback, jsonpCallback().

Example: JSONP Request with a Custom Callback Name

You can change the callback name by adding a callback parameter to the url.

Here we set the callback to myCb by adding ?callback=myCb:

curl -i 'http://localhost:3000/users/tester.jsonp?callback=myCb'

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: text/javascript
Content-Length: 244
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

myCb({
  "user": {
    "username": "tester",
    "join_date": "2013-12-02T20:41:56.735Z",
    "gravatar_id": "cf3321b32988beb65273932bf8de619e",
    "metadata": {
      "username": "tester",
      "repos_count": 1
    }
  },
  "error": null
});

Users

GET /users/:user.json

Get a user's account info.

Params

  • user: The user's username.

Example

curl -i localhost:3000/users/tester.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 237
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "user": {
    "username": "tester",
    "join_date": "2013-12-02T20:41:56.735Z",
    "gravatar_id": "cf3321b32988beb65273932bf8de619e",
    "metadata": {
      "username": "tester",
      "repos_count": 1
    }
  },
  "error": null
}

GET /:user.json

Get a user's account and argument repos.

Params

  • user: The user's username.

Example

curl -i localhost:3000/tester.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 1249
ETag: "787451302"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "user": {
    "username": "tester",
    "join_date": "2013-12-02T20:41:56.735Z",
    "gravatar_id": "cf3321b32988beb65273932bf8de619e",
    "metadata": {
      "username": "tester",
      "repos_count": 1
    },
    "repos": [
      {
        "username": "tester",
        "reponame": "my-argument-^_^",
        "user": {
          "username": "tester",
          "join_date": "2013-12-02T20:41:56.735Z",
          "gravatar_id": "cf3321b32988beb65273932bf8de619e"
        },
        "commit": {
          "object_type": "commit",
          "sha1": "42d835d3dee3cd2964c45ea872553448997744a8",
          "target_type": "argument",
          "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
          "committer": "tester",
          "commit_date": "2013-12-02T20:41:57Z",
          "parent_sha1s": [],
          "host": "testing.argumenta.io"
        },
        "target": {
          "title": "My Argument ^_^",
          "premises": [
            "First premise.",
            "Second premise."
          ],
          "conclusion": "The conclusion! :D",
          "object_type": "argument",
          "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
          "repo": "my-argument-^_^"
        }
      }
    ]
  },
  "error": null
}

Repos

GET /:user/:repo.json

Get a repo owned by a user.

Params

  • user: The repo owner's username.
  • repo: The repo name.

Example

curl -i http://localhost:3000/tester/my-argument-^_^.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 898
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "repo": {
    "username": "tester",
    "reponame": "my-argument-^_^",
    "user": {
      "username": "tester",
      "join_date": "2013-12-02T20:41:56.735Z",
      "gravatar_id": "cf3321b32988beb65273932bf8de619e"
    },
    "commit": {
      "object_type": "commit",
      "sha1": "42d835d3dee3cd2964c45ea872553448997744a8",
      "target_type": "argument",
      "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "committer": "tester",
      "commit_date": "2013-12-02T20:41:57Z",
      "parent_sha1s": [],
      "host": "testing.argumenta.io"
    },
    "target": {
      "title": "My Argument ^_^",
      "premises": [
        "First premise.",
        "Second premise."
      ],
      "conclusion": "The conclusion! :D",
      "object_type": "argument",
      "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "repo": "my-argument-^_^"
    }
  },
  "error": null
}

Arguments

GET /arguments/:sha1.json

Get an argument by its sha1.

Params

  • sha1 - The argument's sha1.

Notes

  • Includes the argument's propositions and original commit for convenience.

Example

curl -i http://localhost:3000/arguments/675f1c4a2a2bec4fa1e5b745a4b94322dda294e6.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 2256
ETag: "-1982655459"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "argument": {
    "title": "My Argument ^_^",
    "premises": [
      "First premise.",
      "Second premise."
    ],
    "conclusion": "The conclusion! :D",
    "object_type": "argument",
    "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
    "repo": "my-argument-^_^",
    "commit": {
      "object_type": "commit",
      "sha1": "42d835d3dee3cd2964c45ea872553448997744a8",
      "target_type": "argument",
      "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "committer": "tester",
      "commit_date": "2013-12-02T20:41:57Z",
      "parent_sha1s": [],
      "host": "testing.argumenta.io"
    },
    "propositions": [
      {
        "text": "First premise.",
        "object_type": "proposition",
        "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
        "metadata": {
          "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
          "tag_sha1s": {
            "support": [],
            "dispute": [],
            "citation": []
          },
          "tag_counts": {
            "support": 0,
            "dispute": 0,
            "citation": 0
          }
        }
      },
      {
        "text": "Second premise.",
        "object_type": "proposition",
        "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
        "metadata": {
          "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
          "tag_sha1s": {
            "support": [
              "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
            ],
            "dispute": [],
            "citation": [
              "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
            ]
          },
          "tag_counts": {
            "support": 1,
            "dispute": 0,
            "citation": 1
          }
        }
      },
      {
        "text": "The conclusion! :D",
        "object_type": "proposition",
        "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
        "metadata": {
          "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
          "tag_sha1s": {
            "support": [],
            "dispute": [],
            "citation": []
          },
          "tag_counts": {
            "support": 0,
            "dispute": 0,
            "citation": 0
          }
        }
      }
    ]
  },
  "error": null
}

Argument Propositions

GET /arguments/:sha1/propositions.json

Get an argument's propositions.

Params

  • sha1 - The argument's sha1.

Example

curl -i http://localhost:3000/arguments/675f1c4a2a2bec4fa1e5b745a4b94322dda294e6/propositions.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 1789
ETag: "1174394911"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "argument": {
    "title": "My Argument ^_^",
    "premises": [
      "First premise.",
      "Second premise."
    ],
    "conclusion": "The conclusion! :D",
    "object_type": "argument",
    "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
    "repo": "my-argument-^_^"
  },
  "propositions": [
    {
      "text": "First premise.",
      "object_type": "proposition",
      "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
      "metadata": {
        "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
        "tag_sha1s": {
          "support": [],
          "dispute": [],
          "citation": []
        },
        "tag_counts": {
          "support": 0,
          "dispute": 0,
          "citation": 0
        }
      }
    },
    {
      "text": "Second premise.",
      "object_type": "proposition",
      "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "metadata": {
        "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
        "tag_sha1s": {
          "support": [
            "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
          ],
          "dispute": [],
          "citation": [
            "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
          ]
        },
        "tag_counts": {
          "support": 1,
          "dispute": 0,
          "citation": 1
        }
      }
    },
    {
      "text": "The conclusion! :D",
      "object_type": "proposition",
      "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
      "metadata": {
        "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
        "tag_sha1s": {
          "support": [],
          "dispute": [],
          "citation": []
        },
        "tag_counts": {
          "support": 0,
          "dispute": 0,
          "citation": 0
        }
      }
    }
  ],
  "error": null
}

Argument Discussions

GET /arguments/:sha1/discussions.json

Get an argument's discussions.

Params

  • sha1 - The argument's sha1.

Example

curl -i http://localhost:3000/arguments/675f1c4a2a2bec4fa1e5b745a4b94322dda294e6/discussions.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 787
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "discussions": [
    {
      "discussion_id": 1,
      "target_type": "argument",
      "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "target_owner": "tester",
      "creator": "tester",
      "created_at": "2013-12-02T20:41:57.622Z",
      "updated_at": "2013-12-02T20:41:57.622Z",
      "comments": [
        {
          "comment_id": 1,
          "author": "tester",
          "comment_date": "2013-12-02T20:41:57.622Z",
          "comment_text": "The commentary text...",
          "discussion_id": 1
        },
        {
          "comment_id": 2,
          "author": "tester",
          "comment_date": "2013-12-02T20:41:57.732Z",
          "comment_text": "The commentary text...",
          "discussion_id": 1
        }
      ]
    }
  ],
  "error": null
}

Propositions

GET /propositions/:sha1.json

Get a proposition by its sha1.

Params

  • sha1: The proposition's sha1.

Returns

  • Success: 200 (OK)
  • Error: 404 (Not Found)

Example

curl -i http://localhost:3000/propositions/30be8f3b68d20f5c3898265e33c583ddee374a6a.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 565
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "proposition": {
    "text": "Second premise.",
    "object_type": "proposition",
    "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
    "metadata": {
      "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "tag_sha1s": {
        "support": [
          "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
        ],
        "dispute": [],
        "citation": [
          "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
        ]
      },
      "tag_counts": {
        "support": 1,
        "dispute": 0,
        "citation": 1
      }
    }
  },
  "error": null
}

GET /propositions/:sha1/tags.json

Get a proposition's tags.

Params

  • sha1: The proposition's sha1.

Returns

  • Success: 200 (OK)

Example

curl -i http://localhost:3000/propositions/30be8f3b68d20f5c3898265e33c583ddee374a6a/tags.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 683
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "tags": [
    {
      "object_type": "tag",
      "tag_type": "support",
      "target_type": "proposition",
      "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "source_type": "proposition",
      "source_sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
      "sha1": "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
    },
    {
      "object_type": "tag",
      "tag_type": "citation",
      "target_type": "proposition",
      "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "citation_text": "The citation text, with url: http://wikipedia.org/wiki/Citation",
      "sha1": "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
    }
  ],
  "error": null
}

GET /propositions/:sha1/tags-plus-sources.json

Get a proposition's tags (plus source objects).

Params

  • sha1: The proposition's sha1.

Returns

  • Success: 200 (OK)

Example

curl -i http://localhost:3000/propositions/30be8f3b68d20f5c3898265e33c583ddee374a6a/tags-plus-sources.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 1527
ETag: "291248104"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "tags": [
    {
      "object_type": "tag",
      "tag_type": "support",
      "target_type": "proposition",
      "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "source_type": "proposition",
      "source_sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
      "sha1": "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
    },
    {
      "object_type": "tag",
      "tag_type": "citation",
      "target_type": "proposition",
      "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
      "citation_text": "The citation text, with url: http://wikipedia.org/wiki/Citation",
      "sha1": "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
    }
  ],
  "sources": [
    {
      "text": "The conclusion! :D",
      "object_type": "proposition",
      "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e"
    }
  ],
  "commits": [
    {
      "object_type": "commit",
      "sha1": "161c922ab1e861eead5f2b5ce4570b17bd079c1b",
      "target_type": "tag",
      "target_sha1": "08f6c25476af45f8d8ee4cb0601740bc7bf098ab",
      "committer": "tester",
      "commit_date": "2013-12-02T20:41:57Z",
      "parent_sha1s": [],
      "host": "testing.argumenta.io"
    },
    {
      "object_type": "commit",
      "sha1": "f3c0b481e392e4b9fc5c84205381cbbac08fcdda",
      "target_type": "tag",
      "target_sha1": "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae",
      "committer": "tester",
      "commit_date": "2013-12-02T20:41:57Z",
      "parent_sha1s": [],
      "host": "testing.argumenta.io"
    }
  ],
  "error": null
}

Tags

GET /tags/:sha1.json

Get a tag by its sha1.

Params

  • sha1: The tag's sha1.

Returns

  • Success: 200 (OK)
  • Error: 404 (Not Found)

Example

curl -i http://localhost:3000/tags/412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 329
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "tag": {
    "object_type": "tag",
    "tag_type": "citation",
    "target_type": "proposition",
    "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
    "citation_text": "The citation text, with url: http://wikipedia.org/wiki/Citation",
    "sha1": "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
  },
  "error": null
}

Discussions

GET /discussions/:id.json

Get a discussion by id.

Params

  • id: The discussion id.

Returns

  • Success: 200 (OK)
  • Error: 404 (Not Found)

Example

curl -i http://localhost:3000/discussions/1.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 728
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "discussion": {
    "discussion_id": 1,
    "target_type": "argument",
    "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
    "target_owner": "tester",
    "creator": "tester",
    "created_at": "2013-12-02T20:41:57.622Z",
    "updated_at": "2013-12-02T20:41:57.622Z",
    "comments": [
      {
        "comment_id": 1,
        "author": "tester",
        "comment_date": "2013-12-02T20:41:57.622Z",
        "comment_text": "The commentary text...",
        "discussion_id": 1
      },
      {
        "comment_id": 2,
        "author": "tester",
        "comment_date": "2013-12-02T20:41:57.732Z",
        "comment_text": "The commentary text...",
        "discussion_id": 1
      }
    ]
  },
  "error": null
}

Comments

GET /comments/:id.json

Get a comment by id.

Params

  • id: The comment id.

Returns

  • Success: 200 (OK)
  • Error: 404 (Not Found)

Example

curl -i http://localhost:3000/comments/1.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 201
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "comment": {
    "comment_id": 1,
    "author": "tester",
    "comment_date": "2013-12-02T20:41:57.622Z",
    "comment_text": "The commentary text...",
    "discussion_id": 1
  },
  "error": null
}

Search

GET /search.json

GET /search/:query.json

Search by query for users, arguments, and propositions.

Notes

For convenience, you may use the query param in the URL's path or query string.

Params

  • query: The search query. (Example: "My Argument")

Returns

  • Success: 200 (OK)
  • Error: 404 (Not Found)

Example with search in query string

curl -i http://localhost:3000/search.json?query=My+Argument

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 2464
ETag: "1665290217"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "arguments": [
    {
      "title": "My Argument ^_^",
      "premises": [
        "First premise.",
        "Second premise."
      ],
      "conclusion": "The conclusion! :D",
      "object_type": "argument",
      "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "repo": "my-argument-^_^",
      "commit": {
        "object_type": "commit",
        "sha1": "42d835d3dee3cd2964c45ea872553448997744a8",
        "target_type": "argument",
        "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
        "committer": "tester",
        "commit_date": "2013-12-02T20:41:57Z",
        "parent_sha1s": [],
        "host": "testing.argumenta.io"
      },
      "propositions": [
        {
          "text": "First premise.",
          "object_type": "proposition",
          "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
          "metadata": {
            "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
            "tag_sha1s": {
              "support": [],
              "dispute": [],
              "citation": []
            },
            "tag_counts": {
              "support": 0,
              "dispute": 0,
              "citation": 0
            }
          }
        },
        {
          "text": "Second premise.",
          "object_type": "proposition",
          "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
          "metadata": {
            "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
            "tag_sha1s": {
              "support": [
                "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
              ],
              "dispute": [],
              "citation": [
                "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
              ]
            },
            "tag_counts": {
              "support": 1,
              "dispute": 0,
              "citation": 1
            }
          }
        },
        {
          "text": "The conclusion! :D",
          "object_type": "proposition",
          "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
          "metadata": {
            "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
            "tag_sha1s": {
              "support": [],
              "dispute": [],
              "citation": []
            },
            "tag_counts": {
              "support": 0,
              "dispute": 0,
              "citation": 0
            }
          }
        }
      ]
    }
  ],
  "propositions": [],
  "users": [],
  "error": null
}

Example with search in path

curl -i http://localhost:3000/search/My%20Argument.json

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 2464
ETag: "1665290217"
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%7D.IduvgXvQtLWjWRgMgYx6LR8eowjCrldCZ8%2BbbmP3IUvBsdFXC19UyOLesqZ5p%2FM5Ez2cVZx%2FaFZgEQy%2B%2BZYsfw; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:58 GMT
Connection: keep-alive

{
  "arguments": [
    {
      "title": "My Argument ^_^",
      "premises": [
        "First premise.",
        "Second premise."
      ],
      "conclusion": "The conclusion! :D",
      "object_type": "argument",
      "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
      "repo": "my-argument-^_^",
      "commit": {
        "object_type": "commit",
        "sha1": "42d835d3dee3cd2964c45ea872553448997744a8",
        "target_type": "argument",
        "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
        "committer": "tester",
        "commit_date": "2013-12-02T20:41:57Z",
        "parent_sha1s": [],
        "host": "testing.argumenta.io"
      },
      "propositions": [
        {
          "text": "First premise.",
          "object_type": "proposition",
          "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
          "metadata": {
            "sha1": "49cb32b909f2cdfad750fd76af83a126414d0e7a",
            "tag_sha1s": {
              "support": [],
              "dispute": [],
              "citation": []
            },
            "tag_counts": {
              "support": 0,
              "dispute": 0,
              "citation": 0
            }
          }
        },
        {
          "text": "Second premise.",
          "object_type": "proposition",
          "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
          "metadata": {
            "sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
            "tag_sha1s": {
              "support": [
                "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
              ],
              "dispute": [],
              "citation": [
                "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
              ]
            },
            "tag_counts": {
              "support": 1,
              "dispute": 0,
              "citation": 1
            }
          }
        },
        {
          "text": "The conclusion! :D",
          "object_type": "proposition",
          "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
          "metadata": {
            "sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
            "tag_sha1s": {
              "support": [],
              "dispute": [],
              "citation": []
            },
            "tag_counts": {
              "support": 0,
              "dispute": 0,
              "citation": 0
            }
          }
        }
      ]
    }
  ],
  "propositions": [],
  "users": [],
  "error": null
}

Session Routes (Authenticated)

Join

POST /users.json

Create a new user account.

Params

  • username: (Required) The new user's username.
  • password: (Required) The new user's password.
  • email: (Required) The new user's email.

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 409 (Resource Conflict)

Example

curl -i -X POST http://localhost:3000/users.json \
  -d 'username=tester' \
  -d 'password=tester12' \
  -d 'email=tester@xyz.com' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 221
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/tester",
  "message": "Welcome aboard, tester!",
  "user": {
    "username": "tester",
    "join_date": "2013-12-02T20:41:56.735Z",
    "gravatar_id": "cf3321b32988beb65273932bf8de619e"
  },
  "error": null
}

Login

POST /login.json

Start an authenticated user session.

Params

  • username: The user's username.
  • password: The user's password.

Returns

  • Success: 200 (OK)
  • Error: 401 (Unauthorized)

Example

curl -i -X POST http://localhost:3000/login.json \
    -d 'username=tester' \
    -d 'password=tester12' \
    -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 76
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:59 GMT
Connection: keep-alive

{
  "url": "/tester",
  "message": "Welcome back, tester",
  "error": null
}

GET /logout.json

End the current user session.

Params

No params.

Returns

  • Success: 200 (OK)

Example

curl -i http://localhost:3000/logout.json \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 74
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22%22%7D.AJY%2Fn4IAE2DtwZfmTqqyhynLvqswFNU3sUzlQ0uCPQqZNWHvHZaOBzcAm5e7ZTbbOSDiPUDpiq4ibWFyTb49ww; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:59 GMT
Connection: keep-alive

{
  "url": "/",
  "message": "Logged out successfully.",
  "error": null
}

Publish

POST /arguments.json

Create a new argument (with repo).

Params

  • title: [Required] The argument title. (100 characters max)
  • premises: [Required] The argument premises. (240 chars max, for each)
  • conclusion: [Required] The argument conclusion. (240 chars max)

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 401 (Unauthorized)

Example

curl -i -X POST http://localhost:3000/arguments.json \
  -d 'title=My Argument ^_^' \
  -d 'premises=First premise.' \
  -d 'premises=Second premise.' \
  -d 'conclusion=The conclusion! :D' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 378
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/tester/my-argument-^_^",
  "message": "Created a new argument!",
  "argument": {
    "title": "My Argument ^_^",
    "premises": [
      "First premise.",
      "Second premise."
    ],
    "conclusion": "The conclusion! :D",
    "object_type": "argument",
    "sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
    "repo": "my-argument-^_^"
  },
  "error": null
}

POST /propositions.json

Create a new proposition.

Params

  • text: [Required] The proposition text. (240 characters max)

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 401 (Unauthorized)

Example

curl -i -X POST http://localhost:3000/propositions.json \
  -d 'text=A new proposition.' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 276
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/propositions/27bb729a697da7d8c0d2513167394ac0798c99f0",
  "message": "Created a new proposition!",
  "proposition": {
    "text": "A new proposition.",
    "object_type": "proposition",
    "sha1": "27bb729a697da7d8c0d2513167394ac0798c99f0"
  },
  "error": null
}

POST /tags.json

Create a new tag (support, dispute, citation, or commentary).

Params

Required for all tag types:

  • tag_type: The tag's type: 'support', 'dispute', 'citation', or 'commentary'.
  • target_type: The target's type: 'argument' or 'proposition'.
  • target_sha1: The target's sha1.

Required for support and dispute tags:

  • source_type: The source's type: 'argument' or 'proposition'.
  • source_sha1: The source's sha1.

Required for citation tags:

  • citation_text: The citation text, which may include urls. (240 chars max)

Required for commentary tags:

  • commentary_text: The commentary text. (2400 chars max)

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 401 (Unauthorized)

Example: Create a Citation Tag

curl -i -X POST http://localhost:3000/tags.json \
  -d 'tag_type=citation' \
  -d 'target_type=proposition' \
  -d 'target_sha1=30be8f3b68d20f5c3898265e33c583ddee374a6a' \
  -d 'citation_text=The citation text, with url: http://wikipedia.org/wiki/Citation' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 423
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/tags/412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae",
  "message": "Created a new tag!",
  "tag": {
    "object_type": "tag",
    "tag_type": "citation",
    "target_type": "proposition",
    "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
    "citation_text": "The citation text, with url: http://wikipedia.org/wiki/Citation",
    "sha1": "412cd5f899b6f01685e7f8ab6cbaf0ef00ebb7ae"
  },
  "error": null
}

Example: Create a Support Tag

curl -i -X POST http://localhost:3000/tags.json \
  -d 'tag_type=support' \
  -d 'target_type=proposition' \
  -d 'target_sha1=30be8f3b68d20f5c3898265e33c583ddee374a6a' \
  -d 'source_type=proposition' \
  -d 'source_sha1=dfe2394f3cdad27e56023cd0574be36b9a5f9e6e' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 431
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/tags/08f6c25476af45f8d8ee4cb0601740bc7bf098ab",
  "message": "Created a new tag!",
  "tag": {
    "object_type": "tag",
    "tag_type": "support",
    "target_type": "proposition",
    "target_sha1": "30be8f3b68d20f5c3898265e33c583ddee374a6a",
    "source_type": "proposition",
    "source_sha1": "dfe2394f3cdad27e56023cd0574be36b9a5f9e6e",
    "sha1": "08f6c25476af45f8d8ee4cb0601740bc7bf098ab"
  },
  "error": null
}

POST /discussions.json

Create a new discussion, with initial comment.

Params

Required values:

  • target_type: The object type of the discussion target. (Allowed values: 'argument')
  • target_sha1: The sha1 of the discussion target.
  • comment_text The text of the initial comment.

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 401 (Unauthorized)

Example

curl -i -X POST http://localhost:3000/discussions.json \
  -d 'target_type=argument' \
  -d 'target_sha1=675f1c4a2a2bec4fa1e5b745a4b94322dda294e6' \
  -d 'comment_text=The commentary text...' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 598
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/discussions/1",
  "message": "Created a new discussion!",
  "discussion": {
    "discussion_id": 1,
    "target_type": "argument",
    "target_sha1": "675f1c4a2a2bec4fa1e5b745a4b94322dda294e6",
    "target_owner": "tester",
    "creator": "tester",
    "created_at": "2013-12-02T20:41:57.622Z",
    "updated_at": "2013-12-02T20:41:57.622Z",
    "comments": [
      {
        "comment_id": 1,
        "author": "tester",
        "comment_date": "2013-12-02T20:41:57.622Z",
        "comment_text": "The commentary text...",
        "discussion_id": 1
      }
    ]
  },
  "error": null
}

POST /comments.json

Create a new comment, for an existing discussion.

Params

Required values:

  • comment_text: The comment text
  • discussion_id: The id of the discussion the comment appears in.

Returns

  • Success: 201 (Created)
  • Error: 400 (Bad Request)
  • Error: 401 (Unauthorized)

Example

curl -i -X POST http://localhost:3000/comments.json \
  -d 'comment_text=The commentary text...' \
  -d 'discussion_id=1' \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 201 Created

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 264
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:57 GMT
Connection: keep-alive

{
  "url": "/comments/2",
  "message": "Created a new comment!",
  "comment": {
    "comment_id": 2,
    "author": "tester",
    "comment_date": "2013-12-02T20:41:57.732Z",
    "comment_text": "The commentary text...",
    "discussion_id": 1
  },
  "error": null
}

Delete

DELETE /:name/:repo.json

Delete a repo.

Notes

Users may only delete their own repos.

Params

  • name: The repo owner's username.
  • repo: The repo name.

Returns

  • Success: 200 (OK)
  • Error: 401 (Unauthorized)
  • Error: 403 (Forbidden)

Example

curl -i -X DELETE http://localhost:3000/tester/arg-to-delete.json \
  -b ~/tmp/cookies -c ~/tmp/cookies

HTTP/1.1 200 OK

X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,PUT,POST
Access-Control-Allow-Headers: Content-Type, Authorization
Content-Type: application/json
Content-Length: 86
Set-Cookie: connect.sess=s%3Aj%3A%7B%22flash%22%3A%7B%7D%2C%22username%22%3A%22tester%22%7D.0bdDTiafhwxCfkA%2BJQumBL17tYkebS5qSQgpuopgH2Kbgv%2B5IjfP6W2h12P4iS0ptBn2oYgOM02djfmZr8jSpA; Path=/; HttpOnly
Date: Mon, 02 Dec 2013 20:41:59 GMT
Connection: keep-alive

{
  "url": "/",
  "message": "Deleted repo 'tester/arg-to-delete'.",
  "error": null
}

Changes

0.1.3

Add Comments and Discussions routes.

0.1.2

Add route for publishing propositions.

0.1.0

Add Search route.
Include metadata with users.
Document resource types and properties.

0.0.1alpha6

Add route to delete a repo.

0.0.1alpha5

Include original commit with argument.

0.0.1alpha4

Include metadata with each proposition.

0.0.1alpha3

Include metadata with argument propositions.

0.0.1alpha2

Add Proposition routes.

0.0.1alpha1

Initial version with routes for Users, Repos, Arguments, Propositions, and Tags.

Jump to Line
Something went wrong with that request. Please try again.