Skip to content

Commit

Permalink
Tweak structure and style changes in dev-manual
Browse files Browse the repository at this point in the history 
Co-authored-by: Jesús García Crespo <[email protected]>
  • Loading branch information
@replaceafill @sevein
replaceafill and sevein committed Jan 21, 2021
1 parent 54959d4 commit 830111d
Show file tree
Hide file tree
Showing 8 changed files with 1,249 additions and 1,184 deletions.
1 change: 1 addition & 0 deletions contents.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,4 @@
getting-started/index
user-manual/index
admin-manual/index
dev-manual/index
116 changes: 68 additions & 48 deletions dev-manual/api/api-overview.rst
View file
Original file line number Diff line number Diff line change
@@ -1,93 +1,113 @@
.. _am-api-overview:
.. _api-overview:

=============
API overview
=============

Archivematica exposes services and resources with the following REST-style APIs that were built using Tastypie, a webservice API framework for Django:
Archivematica exposes services and resources with the following REST-style APIs:

* :ref:`AM-API-intro`
* :ref:`SS-API-intro`
* :ref:`archivematica-api-intro`
* :ref:`storage-service-api-intro`

The Archivematica and Storage service APIs are designed to help you create custom solutions or integrate with RESTful APIs.
The Archivematica and Storage service APIs are designed to help you create
custom solutions.

.. _archivematica-api-intro:

.. _AM-API-intro:

Archivematica API
==================
-----------------

The Archivematica API enables the following:

* Coverage of some basic workflow functionality (e.g. listing and approving workflow tasks awaiting decision).
* Proxy support to the Storage Service.
* Exposing unit status or processing configuration details.

See :ref:`am-api-reference.rst` for information on Archivematica API endpoints.
* Coverage of some basic workflow functionality (e.g. listing and approving
workflow tasks awaiting decision).
* Proxy support to the Storage Service.
* Exposing unit status or processing configuration details.

.. _SS-API-intro:
Archivematica API endpoints require authentication. See
:ref:`Authentication <api-overview-auth>` for additional information.

Storage Service API
====================
See :ref:`api-reference-archivematica` for information on Archivematica API
endpoints.

If your system configuration includes the Archivematica Storage Service, then you may find the Storage Service API helpful for retrieving information about the following resources:
.. _storage-service-api-intro:

* Pipeline
* Space
* Location
Storage Service API
-------------------

Storage Service API endpoints require authentication with a username and API key. See :ref:`Authentication<api-overview-auth>` for additional information.
If your system configuration includes the Archivematica Storage Service, then
you may find the Storage Service API helpful for retrieving information about
the following resources:

===============
Using the APIs
===============
* Pipeline
* Space
* Location

All calls to the API endpoints require authentication with username and API key. These can be submitted as GET parameters (e.g. ``?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2``) or in the header (e.g. ``Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2``).
Storage Service API endpoints require authentication. See
:ref:`Authentication <api-overview-auth>` for additional information.

There are a number of API endpoints in the Archivematica Dashboard, some of which are proxies to the Storage Service. For resource and endpoint descriptions, consult the :ref:`am-api-reference.rst` section.
See :ref:`api-reference-storage-service` for information on Storage Service API
endpoints.

.. _api-overview-auth:

Authentication
===============
^^^^^^^^^^^^^^

Archivematica's Dashboard provides a simple cookie-based user authentication system using the Django authentication framework. Only authenticated users have access to the data.
All calls to the API endpoints require authentication with username and API key.

Both the Archivematica API and Storage Service API use GET parameters by default to give access to authenticated users.
Archivematica's Dashboard provides a simple cookie-based user authentication
system using the Django authentication framework. Only authenticated users have
access to the data.

Both the Archivematica API and Storage Service API use GET parameters by default
to give access to authenticated users.

When setting GET parameters, the format is::

?username=<username>&api_key=<api_key>

If you do not want to pass unencrypted user data via the request header, you can pass an API key value as part of the header with each request.

When passing an API key value as part of the header, the format is::

ApiKey <username>:<api_key>
Authorizatoin: ApiKey <username>:<api_key>

The Transport Layer Security (TLS) protocol should be enabled in the web server
(typically Nginx) to ensure that all data transmitted between clients and the
server is encrypted with secure algorithms and not viewable by third parties.

Generating an API key for a user
=================================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

API keys are associated with user accounts, which you can manage in the Dashboard Administration tab. Archivematica users fall into two categories-- administrators and non-administrators. :ref:`admin-dashboard-users` who are administrators can create and edit user accounts. Administrators can also generate an API key for any user account in the database.
API keys are associated with user accounts, which you can manage in the
Dashboard Administration tab. Archivematica users fall into two categories:
administrators and non-administrators. :ref:`admin-dashboard-users` who are
administrators can create and edit user accounts. Administrators can also
generate an API key for any user account in the database.

To generate an API key for an existing user in Archivematica:

1. Navigate to **Admin > Users**, and then you will be redirected to the Users page.

2. Select the user for whom you would like to generate an API key, and click their username or the **Edit** button. Archivematica will load the user’s Profile page.

3. Click to enable the **Regenerate API key** box.

4. Then click **Save**.

5. In the **Users** page, click the username again to return to that user's profile, and then you will see the regenerated API key.

.. NOTE::
In the Storage Service, an API key is automatically generated for each new user. If you change the password for a given user, then a new API key will be randomly generated for that user.
1. Navigate to **Admin > Users**, and then you will be redirected to the
Users page.
2. Select the user for whom you would like to generate an API key, and click
their username or the **Edit** button. Archivematica will load the user’s
Profile page.
3. Click to enable the **Regenerate API key** box.
4. Then click **Save**.
5. In the **Users** page, click the username again to return to that user's
profile, and then you will see the regenerated API key.

.. note::
In the Storage Service, an API key is automatically generated for each new
user. If you change the password for a given user, then a new API key will be
randomly generated for that user.

Using an API key in a request
==============================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An API key value must be passed with each request to the API endpoints, or no response will be returned. Below is an example of using `curl <https://curl.haxx.se/>`_ to submit the requests with the API key in the header.
An API key value must be passed with each request to the API endpoints, or no
response will be returned. Below is an example of using
`cURL <https://curl.haxx.se/>`_ to submit the requests with the API key in the
header.

*Example request* (using curl)::

Expand Down
Loading

0 comments on commit 830111d

Please sign in to comment.