Draft 1

• API resources uses plural
• POST/PUT requests and all responses uses JSON
• Authentication ...
• Rate limiting ...

GET /users/me returns 200 OK and a user object. User must be authenticated.

{
  "userid": string,
  "username": string,
  "email": string,
  "created": datetime,
  "updated": datetime,
  "summary": {
    "tags": int,
    "articles": int
  },
  "tags": "https://demokratiappen.se/api/v1/users/me/tags",
  "articles": "https://demokratiappen.se/api/v1/users/me/articles",
}

If not authenticated, return 401 Unauthorized.

POST /users/me where body includes a JSON object that specifies which fields to update.

{
  "email": "new email"
}

Return 405 Method Not Allowed if trying to modify a field which is not modifieable.

GET /users/me/tags returns 200 OK and a list of all tags made by user.

{
  "userid": string,
  "tags": [
    {
      "tagid": string,
      "name": string,
      "type": string, 
      "counts": {
        "negative": int,
        "positive": int
      },
      "ref": "https://demokratiappen.se/api/v1/tags/:tagid"
    }
  ]
}

Possible optional parameters to request:

• limit=int
• offset=int

GET /users/me/tags/:tagid to get a specific tag.

{
  "userid": string,
  "tag": {
    "tagid": string,
    "name": string,
    "type": string, 
    "counts": {
      "negative": int,
      "positive": int
    },
    "ref": "https://demokratiappen.se/api/v1/tags/:tagid"
  }
}

Returns 404 Not Found if user hasn't tagged that particular tag.

GET /users/me/articles returns 200 OK and a list of articles by user.

{
  "userid": string,
  "articles": [
    {
      "articleid": string, 
      "title": string,
      "url": string,
      "ref": "https://demokratiappen.se/api/v1/articles/:articleid"
      "tagsInArticle": [
        {
          "tagid": string,
          "name": string,
          "type": string,
          "counts": {
            "negative": int,
            "positive": int
          },
          "ref": "https://demokratiappen.se/api/v1/tags/:tagid"
        }
      ]
    }
  ]
}

Possible optional parameters to request:

• limit=int
• offset=int

GET /users/me/articles/:articleid to get a specific article.

{
  "userid": string,
  "article": {
    "articleid": string, 
    "title": string,
    "url": string,
    "ref": "https://demokratiappen.se/api/v1/articles/:articleid"
    "tagsInArticle": [
      {
        "tagid": string,
        "name": string,
        "type": string,
        "counts": {
          "negative": int,
          "positive": int
        },
        "ref": "https://demokratiappen.se/api/v1/tags/:tagid"
      }
    ]
  }
}

Returns 404 Not Found if user hasn't saved that particular article.

POST /articles/add returns 201 Created and the new article object. User must be authenticated.

Request (all fields are optional unless otherwise stated)

{
  "url": string, // required
  "title": string, 
  "theme": string
}

Response

{
  "article": {
    "articleid": string, 
    "title": string,
    "url": string,
    "ref": "https://demokratiappen.se/api/v1/articles/:articleid"
    "tagsInArticle": [
      {
        "tagid": string,
        "name": string,
        "type": string,
        "ref": "https://demokratiappen.se/api/v1/tags/:tagid"
      }
    ]
  }
}

Once an article is created, a second request can be sent to rate the article. Only one rate request is allowed. All subsequent rate requests return 403 Forbidden.

To rate an article, send a POST /articles/:articleid/rate with the body:

{
  "ratings": [
    {
      "tagid": string,
      "rating": string // negative || positive
    }
  ]
}

Correct requests return 200 OK with an empty body.

If a tagid is not included the tag is left unrated. If at least one tagid is not correct or does not apply for the articleid an error response 400 Bad Request is returned. The body details which tagid is failing. Either all is applied or an error is generated and rating can be redone.

{
  "error": string, // message to user describing the error
  "failed": [:tagid]
}