Atomstore API

Available Atomsore APIs List:

Authentication

Several routes require authentication. The following authentication methods are supported:

Basic:

Http header where CREDENTIALS is base64encode('user:password'):

1
Authorization: Basic CREDENTIALS

Token:

Http header where TOKEN is a token which can be looked up in your account settings or acquired through the API:

1
Authorization: Token TOKEN

Get API Token

This API will return the API token for the authenticated user. If no token exists, one will be generated.

URL: POST /api/v1/token

Authentication: Basic, Session

Example CURL request:

1
curl -X POST http://90.84.172.223/api/v1/token -u "user:password"

Returns: application/json

1
{"token":"4b92477ff8d5fe889be75db4c7d9a09116276920"}

Regenerate API Token

This API will generate and return a new API token for the authenticated user regardless of whether a token already exists.

URL: POST /api/v1/token/new

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -X POST https://90.84.172.223/api/v1/token/new

Returns: application/json

1
{"token":"ca3fb97920705d2c2ecdb0900f8ed5cf5744704d"}

Get All atoms

This API will return a list of all atomstore atoms

URL: GET /api/v1/apps.json

Authentication: None

Example CURL request:

1
curl https://90.84.172.223/api/v1/apps.jon

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[
  {
    "id": "atom_id",
    "categories": [
      {
        "id": "category_id"
      }
    ],
    "translations": {
      "en": {
        "name": "atom_name",
        "summary": "atom_summary",
        "description": "atom_description"
      }
    }
  }
]

Delete Atom

This API will delete an atom, only app owners are allowed to delete an app. The owner is the user that pushes the first release of an app to the store.

URL: DELETE /api/v1/apps/{atom-id}

URL parameters:

  • atom-id: ASCII characters and underscores are allowed.

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -X DELETE https://90.84.172.223/api/v1/apps/<atom-id>

Returns:

  • HTTP 204: If the atom was deleted successfully
  • HTTP 401: If the user is not authenticated
  • HTTP 403: If the user is not authorized to delete the atom
  • HTTP 404: If the atom could not be found

Delete Atom Release

This API will delete an atom release, only app owners are allowed to delete an app. The owner is the user that pushes the first release of an app to the store.

URL: DELETE /api/v1/apps/{atom-id}/releases/{release-version}

URL parameters:

  • atom-id: ASCII characters and underscores are allowed.
  • release-version: semantic version allowed.

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -X DELETE https://90.84.172.223/api/v1/apps/<atom-id>/releases/{release-version}

Returns:

  • HTTP 204: If the atom release was deleted successfully
  • HTTP 401: If the user is not authenticated
  • HTTP 403: If the user is not authorized to delete the atom release
  • HTTP 404: If the atom rlease could not be found

Delete Nightly Atom Release

This API will delete a nightly atom release, only app owners are allowed to delete an app. The owner is the user that pushes the first release of an app to the store.

URL: DELETE /api/v1/apps/{atom-id}/releases/nightly/{release-version}

URL parameters:

  • atom-id: ASCII characters and underscores are allowed.
  • release-version: semantic version allowed.

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -X DELETE https://90.84.172.223/api/v1/apps/<atom-id>/releases/nightly/{release-version}

Returns:

  • HTTP 204: If the atom release was deleted successfully
  • HTTP 401: If the user is not authenticated
  • HTTP 403: If the user is not authorized to delete the atom release
  • HTTP 404: If the atom rlease could not be found

Atom Registration/Update Request

This API is responsible for sending request to register new atom or udpate existing atom info.

URL: POST /api/v1/app-register

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -H 'Content-Type: application/json' -X POST http://90.84.172.223/api/v1/app-request --data <Request-Body>

Request Body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "id": "atom_id",
    "translations": {
        "en": {
            "name": "atom_name",
            "summary": "atom_summary",
            "description": "atom_description"
        }
    },
    "categories": [{"id": "cat_id"}],
    "co_maintainers": ["maintainer_username"],
    "authors": [
        {
            "mail": "auth@mail.com"
        }
    ],
    "screenshots": [
        {
            "url": "atom_url_photo",
            "small_thumbnail": "atom_url_small_photo",
            "ordering": 1
        }
    ]
    "user_docs": "url_user_docs",
    "admin_docs": "url_admin_docs",
    "developer_docs": "url_developer_docs",
    "issue_tracker": "url_issue_tracke",
    "website": "url_website",
}
Key Required Value Comment
id Yes Your Atom ID You can't change your atom id and only numbers,letter,underscore allowed.
translations Yes Name, Summary and Description of your atom and can be multilanguage. Atomstore is multi-language , so you can add multiple translation to your atom.
categories Yes List of categories objects, each one contains the id of existing category. To list all Atomstore categories IDs call this API.
co_maintainers No List of Atomstore usernames who are collabrating with the app owner on this atom. To list all Atomstore Users call this API.
Authors No List of authors objects, each one contains the mail of an existing author. To List all them Atomstore Authors call this API.
screenshots No List of screenshots objects, each one contains photo URL, Small Thumbnail URL, Ordering. You can have multiple screenshot per atom, the one with the lowest ordering number will be chosen as thumbnail for the atom.
user_docs No User Documentation URL
admin_docs No Admin Documentation URL
developer_docs No Developer Documentation URL
issue_tracker No Issue Tracker URL
website No Atom Website

Returns:

  • HTTP 201: If the atom registartion/update request created.
  • HTTP 200: If the atom registartion/update request updated.
  • HTTP 400: If Invalid request body.
  • HTTP 401: If the user is not authenticated.
  • HTTP 403: If the user is not authorized to update the request.

Add New Categroy:

If you want to assign your atom to a category not listed in the Atomstore, You can create your own by adding translations key to the category object.

Categories list will be like this: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    "categories":
    [
      {
        "id": "new_cat",
        "translations": {
            "en": {
                "name": "category_name",
                "description": "category_description"
            }
        }
      }
    ]
}

IMPORTANT NOTES:

  1. Your new category will not be added until the admin approves your request.
  2. If your category is successfully created:
    • You can't update its info.
    • If you want to create another request give only the ID of the new category, otherwise you will get Already Exist Error.

Add New Author:

If you want to assign your atom to an author not listed in the Atomstore, You can create your own by adding mail and name. You could also add author's homepage but this part is optional in the author object.

Authors list will be like this: 

1
2
3
4
5
6
7
8
    "Authors":
    [
      {
          "name": "new_author_name",
          "homepage": "new_auth_homepage",
          "mail": "new_auth@mail.com"
      }
    ]

IMPORTANT NOTES:

  1. Your new author will not be added until the admin approves your request.
  2. If your author is successfully created:
    • You can't update its info.
    • If you want to create another request give only the mail of the new author, otherwise you will get Already Exist Error.

Example of Complex Body Request

Example of sending Atom Registration request with the following info:

  1. Two Translations
  2. Two Categories: first already exists and second one you wish to create.
  3. Two Authors: first already exists and second one you wish to create.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
    "id": "atom_id",
    "translations": {
        "en": {
            "name": "atom_name",
            "summary": "atom_summary",
            "description": "atom_description"
        },
        "fr": {
            "name": "atom_name",
            "summary": "atom_summary",
            "description": "atom_description"
        }
    },
    "categories": [
      {"id": "cat_id"},
      {
        "id": "new_cat",
        "translations": {
            "en": {
                "name": "category_name",
                "description": "category_description"
            }
        }
      }
    ],
    "authors": [
        {
          "mail": "auth@mail.com"
        },
        {
          "name": "new_author_name",
          "homepage": "new_auth_homepage",
          "mail": "new_auth@mail.com"
        }
    ]
}

Atom Release Publish/Update Request

This API is responsible for send request to publish new atom release or update existing one.

URL: POST /api/v1/release-request

Authentication: Basic, Token

Example CURL request:

1
curl -H "Authorization: Token <API-TOKEN>" -H 'Content-Type: application/json' -X POST http://90.84.172.223/api/v1/release-request --data <Request-Body>

Request Body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "atom_id": "atom_id",
    "version": "0.1.0",
    "licenses": [
        {
            "id": "license_id"
        }
    ],
  "is_nightly": true,
  "download":"download_url_link",
  "changelog": "release_changelog"
}
Key Required Value Comment
atom_id Yes Your Atom Id
Version Yes Your Release Version Should meet the Semantic Version Format
Licenses Yes List of Licenses objects, each one contains the id of existing license. To list all Atomstore licenses IDs call this API.
is_nightly No true or false Nightly means that this release is unstable.(updated every night)
download No Atom release download URL
changelog No The Release changelog. Can contain Markdown

Returns:

  • HTTP 201: If the atom release publish/update request created.
  • HTTP 200: If the atom release publish/update request updated.
  • HTTP 400: If Invalid request body.
  • HTTP 401: If the user is not authenticated.
  • HTTP 403: If the user is not authorized to update the request.

Add New License:

If you want to assign your atom to a license not listed in the Atomstore, You can create your own by adding name key to the license object.

Licenses list will be like this: 

1
2
3
4
5
6
7
    "licenses":
    [
      {
          "id": "new_license_id",
          "name": "new_license_name",
      }
    ]

IMPORTANT NOTES:

  1. Your new license will not be added until the admin approves your request.
  2. If your license is successfully created:
    • You can't update its name.
    • If you want to create another request give only the id of the new license, otherwise you will get Already Exist Error.

Get All Categories

This API will return all categories and their translations.

URL: GET /api/v1/categories.json

Example CURL request:

1
curl http://90.84.172.223/api/v1/categories.json

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[
  {
    "id": "category_id",
    "translations": {
      "en": {
        "name": "category_name",
        "description": ""
      },
      "fr": {
        "name": "Nom de catégorie",
        "description": ""
      }
    }
  }
]

Get All Users

This API will return username, firstname and lastname of all Atomstore normal users.

URL: GET /api/v1/users.json

Example CURL request:

1
curl http://90.84.172.223/api/v1/users.json

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
  {
    "username": "user",
    "firstName": "user_firstname",
    "lastName": "user_lastname"
  },
  {
    "username": "user2",
    "firstName": "user2_firstname",
    "lastName": "user2_lastname"
  }
]

Get All Authors

This API will return all Atomstore Authors.

URL: GET /api/v1/authors.json

Example CURL request:

1
curl http://90.84.172.223/api/v1/authors.json

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
  {
    "name": "author_name",
    "homepage": "auth_homepage",
    "mail": "auth@mail.com"
  },
  {
    "name": "author2_name",
    "homepage": "auth2_homepage",
    "mail": "auth2@mail.com"
  },
]

Get All Licenses

This API will return all Atomstore licenses.

URL: GET /api/v1/licenses.json

Example CURL request:

1
curl http://90.84.172.223/api/v1/licenses.json

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[
  {
    "id": "license_id",
    "name": "license_name"
  },
  {
    "id": "license_id",
    "name": "license_name"
  }
]

Get Atom Ratings

This API will list all users ratings and comments on the atoms.

URL: GET /api/v1/rating.json

Authentication: None

Example CURL request:

1
curl https://90.84.172.223/api/v1/rating.json

Returns: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[
  {
    "rating": 1,
    "ratedAt": "2016-09-03T17:11:38.772856Z",
    "translations": {
      "en": {
        "comment": "I like it"
      }
    },
    "user": {
      "id": 1,
      "firstName": "Tom",
      "lastName": "Jones"
    },
    "app": "atom_id"
  }
]

Get Server Status

This API will returns the health of the backend (is it reachable or not)

URL: GET /api/v1/status

Authentication: None

Example CURL request:

1
curl  https://90.84.172.223/api/v1/rating.json

Returns: application/json

  • HTTP 200:
1
2
3
4
{
"status": "Healthy",
"backend": "Reachable"
}
  • HTTP 400: can't reach to the backend