Add an API to Coral (Issue #7)

[veggiematts]

Coral is currently missing an API, in order to be able to gather informations or interact with coral from within third-part applications.

API

This merge request offers an API based on Flight as it's simple, lightweight, and quick to use.
http://flightphp.com/

The goal was to be able to submit a resource through the API.

For this purpose, the following functions are implemented in resources/api/ :
/proposeResource/
/version/
/getResourceTypes/
/getResourceType/@id
/getAcquisitionTypes/
/getAcquisitionType/@id
/getResourceFormats/
/getResourceFormat/@id
/getAdministeringSites/
/getAdministeringSite/@id

Client Form

An example client form based on Unirest ( http://unirest.io/php.html ) is provided in resources/api_client/

Configuration

Server-side:

Edit resources/admin/configuration.ini and fill apiAuthorizedIP with the IP address of the client accessing the API:
apiAuthorizedIP="192.168.1.1"

You can set multiple IPs (comma-separated):
apiAuthorizedIP="192.168.1.1,192.168.2"

You can also set incomplete IPs so the whole range will be allowed:
apiAuthorizedIP="192.168.1"
(will authorize all IPs from 192.168.1.1 to 192.168.1.255)

If you are trying to test the example form and it is on the same machine as Coral, 127.0.0.1 should work.

Hint: if you don't know which IP address will be requesting the API, just leave apiAuthorizedIP blank (apiAuthorizedIP="") and access the example form with your browser ( http://yourcoral.tld/resources/api_client/ ), you will get an error like this:
You are not authorized to use this service.
Unauthorized IP: 127.0.0.1

Client-side:

Edit api_client/index.php and set the $server variable:
$server = "http://yourcoral.tld/resources/api/";

Screenshots:

Example form using the API before submit

Example form using the API after submit

[xsong9]

The API will allows CORAL users, for example a selector or subject librarian, to submit a resource into CORAL by filling out an online form outside of CORAL. Fields on the form are mapped directly to the corresponding fields in CORAL after the form is submitted. The summary page can be saved or printed in the browser for the sake of record-keeping.

[fondrenlibrary]

In How-TO or README, users should be told explicitly that

1. the new directive of apiAuthorizedIP="xx.xxx.xx" must be put under the [settings] section in the configurarion.ini . If the loopback interface needs to access this API, use 1 for the loopback interface 127.0.0.1
2. AllowOverride set to ALL in httpd.conf or other related Apache conf file for Coral's root or its resources directory in order for .htaccess of PHP Flight to function as expected. Otherwise users will see 404 Not Found Error.

[veggiematts]

Should I use the README in the resources directory or create a new one in the API directory ?

[fondrenlibrary]

At least having one in the API directory is a practical choice and putting in the Resource README an entry leading to the one in the API directory may also help users. My two cents.

[veggiematts]

README added.

[remocrevo]

I think we need a better way to include separate projects with CORAL (e.g. Flight). Rather than add their code to the CORAL repository, we could simply add instructions to the CORAL installation/upgrade docs about installing those projects to work with CORAL. These are often called "dependencies", and there are projects that can manage your dependencies (yes, projects for managing other projects!). But simply including the steps in the install instructions should be enough for now.

[tuxayo]

I think we need a better way to include separate projects with CORAL (e.g. Flight). Rather than add their code to the CORAL repository, [...] These are often called "dependencies", and there are projects that can manage your dependencies (yes, projects for managing other projects!). [...]

Like Composer? I'm using it for my automated tests experiments (for which the results should come at the end of this week or next one) and it's quite simple to install and there is a package for Flight https://packagist.org/packages/mikecao/flight

[veggiematts]

Dependancies have been removed and INSTALL files have been added.

[benheet]

@remocrevo have your concerns been addressed on this one? Also, do we want to make mention somewhere that flight requires php 5.3 or allow folks to find that out when they link to the flight website?

[benheet]

I'm not quite sure of the necessity for the use case, allowing selectors to submit requests from outside coral. doesn't view only permission allow users to add new records within the resources module without giving subsequent edit rights? That doesn't deny the value of an API though so that's not an objection to this feature at all.

[techsvcslib]

No, I do not think that view only permissions allows anyone the ability to create a new record in the resources module. View only users can submit feedback about a particular resource but they are allowed to create a new record.

[benheet]

Thanks Steve. I haven't used that permission in a while. Now i'm remembering that when this first came up we just trusted our selectors with the add/edit rights but didn't give them the 'view accounts' access so they didn't get their hands on the admin logins. I'd consider an additional permission level (or giving add rights to the view only permission) as a way of supporting selector input in addition to this api work.

[remocrevo]

@tuxayo Yes, Composer would be an option for managing CORAL's dependencies. @veggiematts What is your opinion on removing Flight from this commit and either adding instructions for using Composer, or simply adding a link to the install instructions that says "Install version ABC of Flight"?

[remocrevo]

@benheet The version of PHP required by CORAL dependencies like Flight will change the version of PHP that is required to run those features of CORAL. If those features are optional (i.e. CORAL won't break until you turn on those features), then I think it's helpful to tell users if those features have a higher requirement than the rest of CORAL. But yes, it's certainly good for us to keep aware of the PHP requirements we are working with.

[benheet]

@remocrevo @veggiematts does the current state of this pull request properly deal with how you decided best to deal with dependencies? If so then perhaps we can go ahead and merge this since there are no noted conflicts.

[xsong9]

Please let me know if this is going to be merged. I can start working on the documentation as part of the 2.0 documentation. Thanks!

[benheet]

Remington made a suggestion in an earlier comment about removing Flight from the commit. I wasn't sure how that suggestion was resolved. If it's been resolved then this can be merged.

[remocrevo]

@benheet Nothing has been done yet. Mainly, I'd like to hear opinions from a few others (like @jeffnm, @veggiematts, @bdroubay, @doug-hahn) about how CORAL should manage subprojects that we depend on. Include them in our code base (like this pull request currently does)? Require users to install them separately? Use a tool like Composer to mediate the process? Avoid dependencies whenever possible? In the end, there may be very few differences between those paths, but now is the time to make the decision so we don't do it three different ways.

[benheet]

Thanks Remington. @t4k chime in here too please if you have thoughts on how we should handle this.

[fondrenlibrary]

I think it's fine to include this API add-on into Coral's code base, and it's a step necessary for Coral to join other larger library ecosystems like Folio.

[benheet]

It seems like the discussion on the approach going forward for including 3rd party software is one that's going to take a while and likely not something we'll finish off in a comment thread. I went ahead and merged this since there were no objections to its inclusion just concern about how to do this going forward. We should keep the discussion going and decide an approach before the next 3rd party software comes into play (which may be a while?)

[tuxayo]

We should keep the discussion going and decide an approach before the next 3rd party software comes into play (which may be a while?)

Well, with #130 merged into master, more 3rd party software just came into play and it's managed with Composer. So the discussion will be whether to keep using it or not and if yes, use it to manage Flight.

[benheet]

Thank you @tuxayo for pointing that out. Perhaps we should add an Issue to have the API updated later to use Composer as well.