ditup.org REST API documentation version v1

https://api.ditup.org/{version}

version: required (v1)

/users

/users get post

get

The following data can be received:

new users: ?sort=-created&page[offset]=0&page[limit]=5
users with my tags ?filter[byMyTags]
users by tags ?filter[tag]=tag1,tag2,tag3 TODO rename
new users with my tags: ?sort=-created&filter[withMyTags]=2&page[offset]=5&page[limit]=3
users within a rectangle: ?filter[location]=-1.0,-1.0,1.0,1.0

post

Create a new user with unverified email. Verification message will be sent to the provided email.

get /users

The following data can be received:

new users: ?sort=-created&page[offset]=0&page[limit]=5
users with my tags ?filter[byMyTags]
users by tags ?filter[tag]=tag1,tag2,tag3 TODO rename
new users with my tags: ?sort=-created&filter[withMyTags]=2&page[offset]=5&page[limit]=3
users within a rectangle: ?filter[location]=-1.0,-1.0,1.0,1.0

Request
Response

Query Parameters

filter: (object)
- tag: (string)
  a comma separated list of tags to search by
- byMyTags: (nil)
  perform a search by tags which i (logged user) have
- withMyTags: (integer)
  Amount of tags which found users should have in common with me. Used in connection with sort=-created
- location: (string)
  A rectangle to search within - southWestLatitude,southWestLongitude,northEastLatitude,northEastLongitude.
sort: (-created)
if sort=-created is specified, new users will be returned
page: (object)
support for pagination
- offset: required (integer)
  offset of the documents to return (which is the first document to return?)
- limit: required (integer)
  amount of documents to return

HTTP status code 200

HTTP status code 400

post /users

Create a new user with unverified email. Verification message will be sent to the provided email.

Request
Response

Body

Media type: application/vnd.api+json

Type: object

Example:

{
  "data": {
    "type": "users",
    "attributes": {
      "username": "user1",
      "email": "user1@example.com",
      "password": "correcthorsebatterystaple"
    }
  }
}

HTTP status code 201

Success.

Body

Media type: application/vnd.api+json

Type: object

Example:

{
  "data": {
    "type": "users",
    "id": "user1",
    "attributes": {
      "username": "user1",
      "givenName": null,
      "familyName": null,
      "description": null,
      "location": null
    }
  }
}

HTTP status code 400

Validation error.

HTTP status code 409

Conflict. Username must be unique.

/users/{username} get patch

get

patch

Edit user profile (givenName, familyName, description, location).

get /users/{username}

Request
Response

URI Parameters

username: required (string)

HTTP status code 200

HTTP status code 404

User doesn't exist.

patch /users/{username}

Edit user profile (givenName, familyName, description, location).

Request
Response

URI Parameters

username: required (string)

HTTP status code 200

HTTP status code 400

HTTP status code 403

/users/{username}/avatar get patch

get

Get an avatar image of an user. Specifying size is supported.

patch

Upload avatar image. Maximum size is 2MB.

get /users/{username}/avatar

Get an avatar image of an user. Specifying size is supported.

Request
Response

URI Parameters

username: required (string)

Query Parameters

filter: (object)
- size: required (one of 16, 32, 64, 128, 256, 512)
  Return avatar of a specified size.

HTTP status code 200

Body

Media type: image/svg+xml

Type: object

Media type: image/jpeg

Type: object

HTTP status code 403

HTTP status code 404

patch /users/{username}/avatar

Upload avatar image. Maximum size is 2MB.

Request
Response

URI Parameters

username: required (string)

Body

Media type: multipart/form-data

Type: object

HTTP status code 200

HTTP status code 400

HTTP status code 403

/users/{username}/tags get post

get

Get a list of user's tags (with story and relevance).

post

Add a tag to self and specify story and relevance.

get /users/{username}/tags

Get a list of user's tags (with story and relevance).

Request
Response

URI Parameters

username: required (string)

HTTP status code 200

post /users/{username}/tags

Add a tag to self and specify story and relevance.

Request
Response

URI Parameters

username: required (string)

HTTP status code 201

HTTP status code 400

HTTP status code 403

HTTP status code 404

HTTP status code 409

/users/{username}/tags/{tagname} get patch delete

get

Show a tag and user's story and relevance.

patch

Update user's story and/or relevance to a tag.

delete

Remove a tag from a user.

get /users/{username}/tags/{tagname}

Show a tag and user's story and relevance.

Request
Response

URI Parameters

username: required (string)
tagname: required (string)

HTTP status code 200

patch /users/{username}/tags/{tagname}

Update user's story and/or relevance to a tag.

Request
Response

URI Parameters

username: required (string)
tagname: required (string)

HTTP status code 200

HTTP status code 400

HTTP status code 403

HTTP status code 404

delete /users/{username}/tags/{tagname}

Remove a tag from a user.

Request
Response

URI Parameters

username: required (string)
tagname: required (string)

HTTP status code 204

HTTP status code 403

HTTP status code 404

/auth

/auth/token get

get

Send Basic auth header and receive JWT token.

get /auth/token

Send Basic auth header and receive JWT token.

Response

HTTP status code 200

Body

Media type: application/vnd.api+json

Type: object

Example:

{
  "meta": {
    "token": "aaa.bbb.ccc"
  }
}

HTTP status code 401

/auth/exp get

get

Get time till a provided token's expiration [seconds].

get /auth/exp

Get time till a provided token's expiration [seconds].

Response

HTTP status code 200

Body

Media type: application/vnd.api+json

Type: object

Example:

{
  "meta": {
    "exp": 3600
  }
}

HTTP status code 403

/account

/account patch

patch

The following actions are supported:

send email with code for resetting forgotten password
reset forgotten password with reset code
update unverified email and send verification link
verify email
change password

patch /account

The following actions are supported:

send email with code for resetting forgotten password
reset forgotten password with reset code
update unverified email and send verification link
verify email
change password

Request

Query Parameters

reset-password: (nil)
Send email with code for resetting forgotten password

/contacts

/contacts get post

get

Show trust and reference which user gave or received. Don't show unconfirmed contacts to 3rd users. Don't show trust and reference to user who received contact request and didn't confirm, yet.

post

Create a contact request.

get /contacts

Show trust and reference which user gave or received. Don't show unconfirmed contacts to 3rd users. Don't show trust and reference to user who received contact request and didn't confirm, yet.

Request

Query Parameters

filter: required (object)
- from: (string)
  Read contacts given by the specified user.
- to: (string)
  Read contacts given to the specified user.

post /contacts

Create a contact request.

Response

HTTP status code 201

HTTP status code 400

HTTP status code 403

HTTP status code 404

HTTP status code 409

/contacts/{from}/{to} get patch delete

get

Show a contact between two users including reference and trust given by :from to :to

the requester should see unconfirmed contact including message
the requested should see only the message of the unconfirmed contact
every other logged user can see only confirmed contacts (trust and reference)

patch

The following actions are supported:

confirm a contact request
update a contact from self

delete

Delete a contact.

get /contacts/{from}/{to}

Show a contact between two users including reference and trust given by :from to :to

the requester should see unconfirmed contact including message
the requested should see only the message of the unconfirmed contact
every other logged user can see only confirmed contacts (trust and reference)

Request

URI Parameters

from: required (string)
to: required (string)

patch /contacts/{from}/{to}

The following actions are supported:

confirm a contact request
update a contact from self

Request
Response

URI Parameters

from: required (string)
to: required (string)

HTTP status code 200

HTTP status code 400

HTTP status code 403

HTTP status code 404

delete /contacts/{from}/{to}

Delete a contact.

Request

URI Parameters

from: required (string)
to: required (string)

/messages

/messages post get

post

Create a new message to another user.

get

The following information can be retrieved:

messages with another user
threads
amount of threads with unread messages

post /messages

Create a new message to another user.

get /messages

The following information can be retrieved:

messages with another user
threads
amount of threads with unread messages

Request
Response

Query Parameters

filter: required (object)
- count: required (nil)
  Show amount of unread threads.
- threads: required (nil)
  Show last messages of my threads sorted by time.
- with: required (string)
  Show messages with the given user from newest to oldest.

HTTP status code 200

HTTP status code 403

HTTP status code 404

/messages/{id} patch

patch

Set read to true on the message and all the previous unread messages.

patch /messages/{id}

Set read to true on the message and all the previous unread messages.

Request
Response

URI Parameters

id: required (string)

HTTP status code 200

HTTP status code 403

/tags

/tags get post

get

The following data can be received

tags with names similar to a given string (similarity = one of the words in tagname starts with the given string) (?filter[tagname][like]=fraction-of-tag-name)
tags related to my tags ?filter[relatedToMyTags]
tags related to given tags ?filter[relatedToTags]=tag1,tag2,tag3
random tags ?filter[random]
popular tags by amount of uses ?sort=-popularityByUses TODO: new tags (which have some uses)

post

Create a new tag.

get /tags

The following data can be received

tags with names similar to a given string (similarity = one of the words in tagname starts with the given string) (?filter[tagname][like]=fraction-of-tag-name)
tags related to my tags ?filter[relatedToMyTags]
tags related to given tags ?filter[relatedToTags]=tag1,tag2,tag3
random tags ?filter[random]
popular tags by amount of uses ?sort=-popularityByUses TODO: new tags (which have some uses)

Request
Response

Query Parameters

filter: (object)
- tagname: required (object)
  - like: required (string)
- relatedToMyTags: required (nil)
- relatedToTags: required (string)
  a comma separated list of tags to search from
- random: required (nil)
sort: (-popularityByUses)
if sort=-popularityByUses is specified, popular tags will be returned