API Considerations

HTTP/1.1

Features available in the HTTP/1.1 protocol or common extensions thereof SHOULD NOT be duplicated in message bodies or other, out-of-bounds, communication. Example features are those provided by HTTP/1.1’s Cache-Control, ETag, Expires, If-(None-)Match, If-(Un)Modified-Since, Last-Modified, Location, and Vary headers.

Authentication

Implementing web services MUST have some means of authentication, particularly for write operations. This API doesn't presume any particular authentication mechanism. Commonly used authentication mechanisms for HTTP/1.1 are HTTP Basic Authentication and HTTP Digest Authentication (both part of the HTTP/1.1 protocol) and X.509 client-side authentication (part of SSL, which is used in HTTPS). Federated authentication and authorization mechanisms, such as Kerberos and Shibboleth, are increasingly popular.

Authorization

Web service implementations can follow 3 different authorization strategies:

1. Follow Handle’s authorization scheme
   Handle has its own authorization scheme RFC3651. In the web service, each authenticated user is mapped to a Handle Administrator (defined in terms of a : pair). Multiple authenticated web service users may be mapped to a single Handle administrator. In the trivial case, all web service users are mapped to a single Handle administrator. Each permission that is granted to this Handle Administrator is also granted to the web service user, and each permission denied to this Handle Administrator is also denied to the web service user.

2. Follow a different authorization scheme (fully ignoring Handle’s)
   The web service uses a different authorization schema, possibly with different accounts, groups, roles, permissions, granularity etcetera. The authorization data may be stored either

   • as Handle values (recommended); if the Handle System will, at some point in the future, support multiple primaries per LHS, then storing authorization info as Handle values makes it trivial to have multiple web service instances at multiple primaries for redundancy.

   • or otherwise (not recommended), eg. in a separate database, database table, or database table column. To facilitate having multiple web service instances for redundancy, this authorization information will somehow have to be replicated synchronous with Handle's own replication. This will be hard, if not impossible, to implement.

3. Use some blend of both Handle’s authorization scheme and some other authorization scheme

The core API MUST NOT force implementations into any particular authorization strategy.

Interaction between Handle server and web service

The web service and Handle server can cooperate in various modes: Please note that these modes are mutually exclusive, but not collectively exhaustive.

• A: The Handle server operates just like any “stand-alone” Handle server. The web service operates “non-intrusively”: for extra performance and/or functionality, it reads directly from the database. All write-operations are executed through the Handle server. This mode of operation has several implications:

  • The performance of bulk write operations will be limited by the Handle server implementation. For some applications, this (lack of) performance may be unacceptable.

  • If the web service follows authorization semantics other than Handle’s, a problem occurs: actions that are allowed for a user through the web service interface, may not be allowed through the Handle server interface, or vice-versa. These problems can be prevented in two ways:

    1. The web service follows Handle’s authorization semantics completely.

    2. Allow only unauthenticated read-access to the Handle server directly (hence the dashed red arrow between user and Handle server). This way, the web-service is free to enforce its own authorization mechanism.

• B: The web service reads and writes to the database directly, while the Handle server is configured as “read only”. This mode has some consequences:

  • The “transactions log”, normally kept by the Handle server to support efficient mirroring between aprimary and secondary Handle servers, will now have to be kept by the web service. To achieve this, the web service must either

    • interface with CNRI’s Java code for writing to the transactions log, effectively binding (at least parts of) the web service implementation to the Java programming language, or

    • refactor and reimplement this code.

  • All write operations have to go through the web service. This makes it impossible for users use both the Handle server and the web service for administrative actions, or to migrate smoothly between Handle server to web service.

  • The web service can use its own authorization scheme for all write operations (and for any read operations which have no equivalent in the Handle protocol). The authorization semantics can be partly or completely different than Handle’s.

• C: Just like with mode A, the user can read and write to both the web service and the Handle server. However, other than in mode A, both the Handle server and the web service have read and write access to the database.

  • This mode of operation is not (yet) possible with CNRI's current Handle System implementation, but could be arranged in a number of ways (both requiring adaptations to CNRI's Handle server implementation):

    • The web service can notify the Handle server after each write operation. The Handle server can then add this modification to the transactions log in a thread-safe manner.

    • The web service can keep track of all changes it makes in a separate database table. Periodically, the Handle server can read from this table and update the transactions log in a thread safe manner.

  • The user has access to the data through two rather different interfaces: a RESTful web service and the Handle System protocol. Access restrictions for an operation through one interface SHOULD equally apply to the “equivalent” operation on the other interface. This implies that the web service follows Handle’s authorization semantics.

The core API MUST NOT force implementations into any particular authorization strategy.