New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an API to Coral (Issue #7) #41

Merged
merged 11 commits into from Dec 2, 2016

Conversation

Projects
None yet
8 participants
@veggiematts
Contributor

veggiematts commented May 18, 2016

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:

api_client_example
Example form using the API before submit

api_client_submit_example
Example form using the API after submit

veggiematts added some commits Apr 22, 2016

Issue#7: New Resource API
 - Display library as a multiple select list
 - Keep only "Approved" and "Need approval" acquisition types in the demo form
 - Add a summary after resource is added
Issue#7: New Resource API
 - Allow to submit fund without cost and cost without fund
Issue#7: New Resource API
 - Start workflow when available
Issue#7: New Resource API
 - Update client form (textareas)
Issue#7: New Resource API
 - Default values for enterNewWorkflow
 - Add Email class
@xsong9

This comment has been minimized.

Show comment
Hide comment
@xsong9

xsong9 May 18, 2016

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.

xsong9 commented May 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@fondrenlibrary

fondrenlibrary May 18, 2016

Contributor

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.
Contributor

fondrenlibrary commented May 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@veggiematts

veggiematts May 30, 2016

Contributor

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

Contributor

veggiematts commented May 30, 2016

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

@fondrenlibrary

This comment has been minimized.

Show comment
Hide comment
@fondrenlibrary

fondrenlibrary May 31, 2016

Contributor

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.

Contributor

fondrenlibrary commented May 31, 2016

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

This comment has been minimized.

Show comment
Hide comment
@veggiematts

veggiematts Jun 1, 2016

Contributor

README added.

Contributor

veggiematts commented Jun 1, 2016

README added.

@remocrevo

This comment has been minimized.

Show comment
Hide comment
@remocrevo

remocrevo Jul 8, 2016

Member

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.

Member

remocrevo commented Jul 8, 2016

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.

Issue#7: New Resource API
 - License Type Note should be in acquisitions tab.
@tuxayo

This comment has been minimized.

Show comment
Hide comment
@tuxayo

tuxayo Aug 22, 2016

Contributor

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

Contributor

tuxayo commented Aug 22, 2016

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

Issue#7: New Resource API
 - Remove dependancies from Coral
@veggiematts

This comment has been minimized.

Show comment
Hide comment
@veggiematts

veggiematts Oct 14, 2016

Contributor

Dependancies have been removed and INSTALL files have been added.

Contributor

veggiematts commented Oct 14, 2016

Dependancies have been removed and INSTALL files have been added.

@benheet

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Oct 18, 2016

Contributor

@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?

Contributor

benheet commented Oct 18, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Oct 18, 2016

Contributor

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.

Contributor

benheet commented Oct 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@techsvcslib

techsvcslib Oct 18, 2016

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.

techsvcslib commented Oct 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Oct 18, 2016

Contributor

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.

Contributor

benheet commented Oct 18, 2016

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

This comment has been minimized.

Show comment
Hide comment
@remocrevo

remocrevo Oct 19, 2016

Member

@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"?

Member

remocrevo commented Oct 19, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@remocrevo

remocrevo Oct 19, 2016

Member

@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.

Member

remocrevo commented Oct 19, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Nov 16, 2016

Contributor

@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.

Contributor

benheet commented Nov 16, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@xsong9

xsong9 Dec 1, 2016

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!

xsong9 commented Dec 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Dec 1, 2016

Contributor

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.

Contributor

benheet commented Dec 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@remocrevo

remocrevo Dec 1, 2016

Member

@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.

Member

remocrevo commented Dec 1, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Dec 1, 2016

Contributor

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

Contributor

benheet commented Dec 1, 2016

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

@fondrenlibrary

This comment has been minimized.

Show comment
Hide comment
@fondrenlibrary

fondrenlibrary Dec 1, 2016

Contributor

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.

Contributor

fondrenlibrary commented Dec 1, 2016

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 benheet merged commit b200fae into coral-erm:master Dec 2, 2016

@benheet

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Dec 2, 2016

Contributor

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?)

Contributor

benheet commented Dec 2, 2016

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

This comment has been minimized.

Show comment
Hide comment
@tuxayo

tuxayo Dec 4, 2016

Contributor

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.

Contributor

tuxayo commented Dec 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@benheet

benheet Dec 4, 2016

Contributor

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

Contributor

benheet commented Dec 4, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment