Requirements

  1. Infrastructure 
    1. The API-X framework shall be deployable on a separate host from Fedora
      • HTTP requests routed to these instance(s) before being forwarded to their ultimate destination (Fedora, backend service, etc)
    2. It shall be possible to deploy multiple instances of the API-X framework for the sake of scalability of high availability
    3.  The framework shall allow extensions to be hot deployable, configurable, and removable at runtime
    4. Extension services are exposed as HTTP endpoints
    5. API-X shall provide a specification that extensions will implement in order to support high level requirements such as service discovery, binding, etc
  2. Patterns
    1. API-X shall support a filtering pattern in extensions, where an HTTP request to an existing Fedora URI (or response) is routed through an extension and possibly modified in the process
      • The extension is free to do whatever it wants to the request, including route it to an alternate destination, or respond directly
    2. API-X shall support exposing new URIs associated with individual repository resources, bound to individual extensions
    3. API-X shall support exposing URIs associated with the global repository a whole, bound to individual extensions
    4. APi-X shall support a proxy pattern in extensions, where requests to a URI exposed by an extension are proxied to some other web service
      • This can also be seen as implicitly URL rewriting
  3. Service Discovery & Binding
    1. It shall be possible to enumerate the list of all extensions deployed and active within the framework
    2. It shall be possible to enumerate the list of extensions that provide services on a given object in the repository
    3. For any given object in the repository, it shall be possible to enumerate all URIs exposed by extensions
    4. API-X shall provide a mechanism for HTTP clients to discover all URIs exposed by extensions on a given object
    5. It shall be possible to bind extensions to all objects in the repository
    6. It shall be possible to bind extensions to specific objects in the repository, based on their rdf:type

Design considerations

These considerations are non-binding, and represent topics of relevance to the design process.  Decisions related to any of these items are of interest to the stakeholders, and should be communicated where appropriate.

  1. Would it be possible for extensions to be deployable "in close proximity to" an instance of a Fedora implementation (e.g. bundled together as part of an application), for the sake of optimization and/or efficiency?  Can extensions be specified in a way that this is possible?
  2. Would it be possible for The API-X framework to be deployable as an optional add-on module to current reference Fedora implementation,?
    • This would allow standalone Fedora installs to deploy API-X extensions within them
  3. Will the API-X framework to be deployable as OSGi bundles?
    1. The API-X framework could be available as a Karaf Feature, for ease of deployment into Apache Karaf
    2. Will Individual extensions shall be deployable as OSGi bundles?
      1. If so, will they be configurable through OSGi's own ConfigurationAdmin service?
      2. Will creating multiple instances of extensions via ConfgurationAdmin factory pattern shall be allowable?
        • i.e separately configured instances of extensions may be created via means defined by OSGi.
  4. Will the specification for API-X include an abstraction layer used for communicating with Fedora? 

 

  • No labels

23 Comments

  1. A. Soroka

    Several of the point in (1) make guarantees about how Fedora is deployed. Fedora is trying very hard to stop spending so much time making that kind of guarantee about itself and instead concentrate on standardizing its APIs and ontologies.

  2. Aaron Birkland

    Hi Adam,

    Can you elaborate a little more on your observation?.  In particular, which points make guarantees/assumptions about how Fedora is deployed, and what are those guarantees?

  3. A. Soroka

    For example, "The API-X framework shall be deployable as an extension to Fedora" and "Individual extensions shall be deployable as OSGi bundles" together imply that:

    1. Fedora is written to run on the JVM.
    2. Fedora has an extension/plugin system.
    3. Fedora uses OSGi.

    None of which is part of any idea of standardization we have so far contemplated.

  4. Aaron Birkland

    Ah, I see.  The basic idea is that it ought to be possible to provide an instance of a framework targeted to an implementation, so that an extension could be run in close proximity to it.  "close proximity" means that the implementation of an extension could use fcrepo-kernel-api.  Then again, maybe that's not a good thing.  (See for example Elliot's comment).  So maybe there's sufficient reason to -1 this as a requirement?

    1. A. Soroka

      Well, I'm with Elliot Metsger on this, but if you do want to mention this stuff, I would be careful to talk explicitly about relationships to implementations and not to "Fedora in the abstract".

  5. Elliot Metsger

    Aaron Birkland, a point of clarification: what does "container" mean in this case:

    1. The API-X framework shall be deployable within the same container as a Fedora instance

    Does it mean within the same JVM? Within the same Servlet Container?  OSGi Container?

    Likewise (also for clarification):

    The API-X framework shall be deployable as an extension to Fedora

    Is the use of "extension" here meant in a generic sense, as in, "there should be some way to deploy Fedora + API-X Framework as a standalone application" rather than referring to a formal extension mechanism supported by Fedora?

    1. Aaron Birkland

      "Same container" means servlet container or osgi, as appropriate.  For example, if it were possible to distribute API-X as a .war, then there ought to be no inherent reason why Fedora and API-X cannot be deployed in the same servlet container. '

       

      Is the use of "extension" here meant in a generic sense, as in, "there should be some way to deploy Fedora + API-X Framework as a standalone application" rather than referring to a formal extension mechanism supported by Fedora?
      Right, so there really isn't an extension mechanism in Fedora as such, but things can be baked into the same war.  This is the pattern that fcrepo-webapp-plus uses to (for example) add audit or WebAC to Fedora: use Maven to create a custom .war that has Fedora and optional modules.  So that particular requirement is really about finding some way to deploy API-X alongside Fedora into a single application, for the purpose of ease of use (no need to deploy a separate application for API-X), or optimization (extensions could use native Java APIs such as  fcrepo-kernel-api to do things they may not be able to do over the HTTP layer, or do them faster).  Again, it may not be worth the trouble to consider this, and may even be an anti-pattern as far as API-X is concerned, depending on perspective.

      1. A. Soroka

        This is pretty much what I'm warning you against. Supposing someone implements Fedora using Rails? Or Yesod? Or something totally homegrown in Go? We not only want to make that possible, we are trying to get to a place where we can actively encourage people to do that.

        1. Elliot Metsger

          If we consider this pattern of deployment more generically as "embedding Fedora within a larger application" (is this an appropriate characterization of issue being considered on this thread?) - A. Soroka what is your take on embedding Fedora in general?  I mean, do you think that embedding Fedora is a Bad Thing (tm)?  To me embedding would mean a shared runtime between the larger application and the embedded Fedora, and I'm trying to understand whether or not embedding Fedora is a supported (or looked on favorably) use case.

          1. A. Soroka

            From my POV, we're trying to be agnostic about just such questions. We're trying to make "doing Fedora" about the API and the ontologies, not about deployment characteristics or any other kind of implementation-specific question.

            So my honest answer is "No comment." (smile)

             

            1. Elliot Metsger

              Ok, so in that vein, packaging the API-X Framework, any API-X Extensions, and Fedora together in a single application is OK, as long as we're using Fedora's condoned/supported APIs?  And to be explicit about it, your take on this is that fcrepo-kernel-api is a "use at your own risk" API and not one that recommended or supported Fedora integration.  

              1. A. Soroka

                I'm not sure we're quite on the same page yet: I would say "packaging the API-X Framework, any API-X Extensions, and a Fedora implementation together in a single application is OK, as long as we're using Fedora's APIs" period. Do you see what I mean? And as for the Java API, I don't consider it a public API, but I would want to hear from Andrew Woods and Unknown User (acoburn) on that. I suspect they may differ from me.

                For my money, the best thing that could happen here is for you to just take those points about deployment out entirely. I understand that they are desirable, but there is a difference between goals and requirements.

                1. Elliot Metsger

                  Ok, so Aaron Birkland maybe what we should do is consider what impact the deployment goals have on the requirements.

                  If our goal is to support an embedded deployment (e.g. 1b., 1c.) and external deployment (e.g. 1a.), what does that mean in terms of the requirements on the API-X framework or individual extensions.

                  1. Aaron Birkland

                    Sure, let's put this as a specific agenda item for the 2015-12-11 - Fedora API Extensions Meeting.    

                2. Unknown User (acoburn)

                  I agree with A. Soroka about the Java API. I see that as a public API for anyone building a fedora implementation for the JVM, not for anyone building extensions. For software that interacts with Fedora, the public API is the REST API.

        2. Unknown User (acoburn)

          Oh, I'd love to see a fedora implementation built with Yesod. There is a decent RDF library for haskell, but no JSON-LD support (yet).

          1. A. Soroka

            We write down a generic type that represents the existence of a Fedora implementation in Haskell, then a function from nothing (or, at the choice of any repository administrator, everything) to that type. Having proved the existence of the existence of Fedora-on-Haskell, by a left-handed psychedelic variation on Löb's theorem, we have implemented Fedora in Haskell.

          2. A. Soroka

            Is there a reasonable way to index RDF on disc?

  6. Elliot Metsger

    Question on the implications of 3a.: 

      • The extension is free to do whatever it wants to the request, including route it to an alternate destination, or respond directly

    Are extensions allowed to modify the entity body?

  7. Aaron Birkland

    Yes, especially if you think of an http request or response as a kind of message.   If an extension does that, there may be other considerations such as ETag and media type headers, etc.  There is a use case from Amherst related to producing compact jsonld representations of resources.  Consider an extension that filters resource representations from Fedora and converts them to a compact JSON-LD form (or looks this up from a cache), where possible and appropriate. 

    1. Elliot Metsger

      Yes, keeping headers in-line with changes to entity bodies was something I was thinking about.  Another thing I was thinking about was the ordering of activated extensions, potentially parallelizing the execution of extensions, and the interaction between extensions.

  8. Elliot Metsger

    Should it be a requirement of the API-X framework to comport with RFC 2616 (HTTP 1.1)?  And if it does not, be explicit about where it deviates?

    For example, the API-X framework would be considered proxy, specifically a non-transparent proxy.  And the RFC makes recommendations and restrictions regarding their behavior.  A simple example is the Via: header (section 14.45), the Warning: header (section 14.46), and section 13.5.2 (regarding unmodifiable headers).  Can the API-X framework make guarantees about the behaviors of the extensions?  Should it? 

  9. Elliot Metsger

    For 2a, I was thinking the architecture would be required to support hot-deployment, configuration, and removal at runtime, instead of placing that requirement on the extension.

      1. Instances of extensions shall be hot deployable, configurable, and removable at runtime

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.