Below are some comments from one of my developer colleagues, who knows
almost nothing about Fedora, but is working on an application to ingest
objects.
Perhaps the REST API error handling and responses could be improved in
future releases? I could open a ticket for it, if others think it would
be useful, too.
-- Scott
###################################################################
An Outsider's Notes on Working w/ the Fedora REST API
In general: bravo
The API is generally intuitive and makes it clear and easy how to
interact with Fedora. I can create objects, datastreams, relationships
as needed. I got up and running with it right away.
The biggest sign that it is well-designed is that I was able to wire up
a REST client library to it written by someone else (and in another
programming language) and it worked as expected from that library's
understanding of how a REST client should interact w/ a REST API.
Where it needs improvement is in the area of API response messages,
specifically on errors. From the point-of-view of the REST API
consumer, Java stack traces are unhelpful. They are useful in logs,
where developers and application maintainers can go to see them, but to
Fedora users, it is mostly noise.
A concise response is more helpful to application developers using the
RESTful API. I need only three things: 1) an HTTP status code (which I
can get from the headers); 2) a local fedora error code, whether it is
your own numeric codes or other strings like "PIDNotFound" or
"LabelTooLong"; and 3) a concise explanation. (1) and (2) allow me to
gracefully handle the errors (and report them to my own logs) in a way
that I can keep executing for the rest of the content I am trying to
ingest. (3) provides me with some context for the error the first time I
encounter it and lets me know what I should write into my error handling
the next time I encounter the code from (2).
By using the RESTful API, my application treats Fedora as a black box.
Printing the Java stack trace reveals the inner workings of Fedora,
which my application shouldn't see nor care about.
Here's how my ideal response might look:
<fedora-response type="action-failed">
<http-code>415</http-code>
<fedora-error-code>LabelTooLong</fedora-error-code>
<explanation>
Object label must not exceed 255 characters
(foxml:property NAME='info:fedora/fedora-system:def/model#label')
</explanation>
</fedora-response>
This is what I currently get back, and what I don't even attempt to parse:
javax.ws.rs.WebApplicationException:
org.fcrepo.server.errors.ObjectValidityException: <?xml version="1.0"
encoding="UTF-8"?>
<RESULT xmlns:foxml="info:fedora/fedora-system:def/foxml#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
<foxml:property>
<ASSERT>Object label must not exceed 255 characters
(foxml:property NAME='info:fedora/fedora-system:def/model#label')</ASSERT>
</foxml:property>
</RESULT>
at
org.fcrepo.server.rest.BaseRestResource.handleException(BaseRestResource.java:168)
at
org.fcrepo.server.rest.FedoraObjectResource.createObject(FedoraObjectResource.java:298)
at sun.reflect.GeneratedMethodAccessor72.invoke(Unknown Source)
at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at
com.sun.jersey.server.impl.model.method.dispatch.AbstractResourceMethodDispatchProvider$ResponseOutInvoker._dispatch(AbstractResourceMethodDispatchProvider.java:175)
at
com.sun.jersey.server.impl.model.method.dispatch.ResourceJavaMethodDispatcher.dispatch(ResourceJavaMethodDispatcher.java:67)
at
com.sun.jersey.server.impl.uri.rules.HttpMethodRule.accept(HttpMethodRule.java:163)
at
com.sun.jersey.server.impl.uri.rules.ResourceClassRule.accept(ResourceClassRule.java:71)
at
com.sun.jersey.server.impl.uri.rules.RightHandPathRule.accept(RightHandPathRule.java:111)
at
com.sun.jersey.server.impl.uri.rules.RootResourceClassesRule.accept(RootResourceClassesRule.java:63)
at
com.sun.jersey.server.impl.application.WebApplicationImpl._handleRequest(WebApplicationImpl.java:689)
at
com.sun.jersey.server.impl.application.WebApplicationImpl.handleRequest(WebApplicationImpl.java:647)
at
com.sun.jersey.server.impl.application.WebApplicationImpl.handleRequest(WebApplicationImpl.java:638)
at
com.sun.jersey.spi.container.servlet.WebComponent.service(WebComponent.java:309)
at
com.sun.jersey.spi.container.servlet.ServletContainer.service(ServletContainer.java:425)
at
com.sun.jersey.spi.container.servlet.ServletContainer.service(ServletContainer.java:590)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
at
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:290)
at
org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at
org.fcrepo.server.security.servletfilters.FilterRestApiFlash.doFilter(FilterRestApiFlash.java:79)
at
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
at
org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at
org.fcrepo.server.security.jaas.AuthFilterJAAS.doFilter(AuthFilterJAAS.java:287)
at
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
at
org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at
org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:233)
at
org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:191)
at
org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:525)
at
org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:128)
at
org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:102)
at
org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:109)
at
org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:293)
at
org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:849)
at
org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler.process(Http11Protocol.java:583)
at
org.apache.tomcat.util.net.JIoEndpoint$Worker.run(JIoEndpoint.java:454)
at java.lang.Thread.run(Thread.java:637)
Caused by: org.fcrepo.server.errors.ObjectValidityException: <?xml
version="1.0" encoding="UTF-8"?>
<RESULT xmlns:foxml="info:fedora/fedora-system:def/foxml#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
<foxml:property>
<ASSERT>Object label must not exceed 255 characters
(foxml:property NAME='info:fedora/fedora-system:def/model#label')</ASSERT>
</foxml:property>
</RESULT>
at
org.fcrepo.server.validation.DOValidatorSchematron.validate(DOValidatorSchematron.java:132)
at
org.fcrepo.server.validation.DOValidatorSchematron.validate(DOValidatorSchematron.java:87)
at
org.fcrepo.server.validation.DOValidatorImpl.validateByRules(DOValidatorImpl.java:339)
at
org.fcrepo.server.validation.DOValidatorImpl.validate(DOValidatorImpl.java:252)
at
org.fcrepo.server.validation.DOValidatorModule.validate(DOValidatorModule.java:187)
at
org.fcrepo.server.storage.DefaultDOManager.getIngestWriter(DefaultDOManager.java:792)
at
org.fcrepo.server.management.DefaultManagement.ingest(DefaultManagement.java:107)
at sun.reflect.GeneratedMethodAccessor73.invoke(Unknown Source)
at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at
org.fcrepo.server.messaging.NotificationInvocationHandler.invoke(NotificationInvocationHandler.java:68)
at $Proxy0.ingest(Unknown Source)
at
org.fcrepo.server.management.ManagementModule.ingest(ManagementModule.java:336)
at
org.fcrepo.server.rest.FedoraObjectResource.createObject(FedoraObjectResource.java:293)
... 35 more
--
Scott Prater
Library, Instructional, and Research Applications (LIRA)
Division of Information Technology (DoIT)
University of Wisconsin - Madison
[email protected]
------------------------------------------------------------------------------
This SF.net email is sponsored by
Make an app they can't live without
Enter the BlackBerry Developer Challenge
http://p.sf.net/sfu/RIM-dev2dev
_______________________________________________
Fedora-commons-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/fedora-commons-developers
