What routes do we provide for FedoraResource entities?

[dannylamb]

In the end we need something that will let a repository admin browse and manage the tree created by the ldp:contains relationship. I'm trying to keep this pattern as drupal-y as possible. I'm thinking something like

• /entity/islandora
  • List all islandora entities
• /entity/islandora/add
  • Add page for islandora entities. Lets you select what type of entity you want to create.
• /entity/islandora/add/{bundle}
  • The actual form for creating an islandora entity, based on the selection made at /entity/islandora/add
• /entity/islandora/{id}
  • View the entity
• /entity/islandora/{id}/edit
  • Edit form for entity
• /entity/islandora/{id}/delete
  • Deletion form for entity
• /entity/islandora/{id}/children
  • A view of all entities ldp:contain/d by a resource. There should be an action link to add a new resource as a child above the view.
• /entity/islandora/{id}/children/add
  • Add child page for islandora entities. Lets you select what type of entity you want to create.
• /entity/islandora/{id}/children/add/{bundle}
  • The actual form for creating a child, based on the selection made at /entity/islandora. Pre-populates the hasParent field with parent entity.

I'm assuming all of these will be provided as links on the annotation. Thoughts?

[dannylamb]

So it turns out that REST, Views, and Entity routes all kind of stomp all over each other. It's pretty easy to do stuff leads to inconsistencies in route matching. Trying to take a route, like /fedora_resource/{id}, and then adding a view for it at '/fedora_resource/{id}/children' makes Drupal just pick one of the two. It can't sort them out.

So what I was thinking of won't work. A patch has been put into 8.3 to handle this, but until then, maybe we should sandbox REST, entity, and views routes in different contexts. And I wouldn't guarantee that 8.3 will fix all the wonkiness of the interplay between all those systems.

Canonicals

• /islandora/fedora_resource/{id}
  • View the entity
• /islandora/fedora_resource/{id}/edit
  • Edit form for entity
• /islandora/fedora_resource/{id}/delete
  • Deletion form for entity

Administration

• /admin/content/fedora_resource
  • Drupal overview page for fedora resources. Implemented as a view a la Node and Media.
• /admin/content/fedora_resource/add
  • Add page for fedora resources. Lets you select what type of entity you want to create.
• /admin/content/fedora_resource/add/{bundle}
  • The actual form for creating the entity, based on the selection made at /admin/content/fedora_resource/add

LDP Tree stuff

• /islandora/children/{id}
  • A view of all entities ldp:contain/d by a resource.
• /islandora/children/{id}/add
  • Add child page for islandora entities. Lets you select what type of entity you want to create.
• /islandora/children/{id}/add/{bundle}
  The actual form for creating a child, based on the selection made at /islandora/children/{id}/add. Pre-populates the hasParent field with parent entity.
• /islandora/rest/children/{id}
  • REST endpoint for json, jsonld, etc... for the list of children

These should be separate enough, but I have to go through it to know for sure.

[dannylamb]

I'm updating to 8.3 dev to see if that fixes the REST/Views interplay issue.

[dannylamb]

8.3 still has issues. If I make a View with both a page and a rest export, the REST export trumps the page. The _format parameter is not respected, even when forced to 'html'. I'm looking into workarounds, but it's looking like REST and Views are not going to work for us if we want our html routes and REST routes to be the same, since content negotiation is a total fail.

[dannylamb]

After the committers call on Nov. 9th, there was enough discussion to warrant moving forward using the underlying symfony componentry and avoiding views/rest exports. This would not prevent others from implementing views, but the core API GET requests would not use them.

[ruebot]

https://github.com/Islandora-CLAW/CLAW/wiki/November-9%2C-2016

[dannylamb]

So here's the api I want. I'm sticking with /islandora/object as the main context to the api as homage to current stack, but I'm flexible on that naming.

I think it pretty clearly makes a distinction between what I would consider 'core' and 'pcdm' functionality. Athough I'm not designating it in the route. That should also be discussed.

Hopefully by moving forward using the Symfony componentry I can actually implement this without random Drupal issue X blocking my path.

Core

Entities

• GET /islandora/object/{id}
  • Retrieve a representation of an entity, using the _format parameter for content negotiation (e.g. respects available Drupal serializers).
• POST /islandora/object
  • Create an islandora entity from a supplied representation, respecting available Drupal serializers
• PATCH /islandora/object
  • Update an islandora entity from a supplied representation, respecting available Drupal serializers. Allows for conditional updates.
• DELETE /islandora/object/{id}
  • Delete an islandora entity and its children recursively.

Revisions

• GET /islandora/object/{id}/revisions
  • Get a list of revisions for an entity
• GET /islandora/object/{id}/revisions/{revisionId}
  • Get a particular revisions for an entity
• POST /islandora/object/{id}/revisions
  • Create a new revision of an entity from its current state
• PATCH /islandora/object/{id}/revisions/{revisionId}
  • Revert an entity to the specified revision
• DELETE /islandora/object/{id}/revsions/{revisionId}
  • Delete a revision

Children

• GET /islandora/object/{id}/children
  • Retrieve a list of children entities (e.g. all entities whose fedora:hasParent is the entity in the route) , respecting available Drupal serializers.
• POST /islandora/object/{id}/children
  • Create an islandora entity from a supplied representation, making it the child of the entity in the route, respecting available Drupal serializers

PCDM

Membership

• GET /islandora/object/{id}/members
  • Retrieve a list of member entities (e.g. all entities whose pcdm:memberOf is the entity in the route) , respecting available Drupal serializers.
• POST /islandora/object/{id}/members
  • Create an islandora entity from a supplied representation, making it a member of the entity in the route, respecting available Drupal serializers
• PATCH /islandora/object/{id}/members/{memberId}
  • Add an existing entity as a member to the entity in the route.
• DELETE /islandora/object/{id}/members/{memberId}
  • Remove an existing entity as a member to the entity in the route.

Files

• GET /islandora/object/{id}/files
  • Retrieve a list of file entities (e.g. all entities whose pcdm:fileOf is the entity in the route) , respecting available Drupal serializers.
• POST /islandora/object/{id}/files
  • Create a file from a supplied representation, making it a file of the entity in the route, respecting available Drupal serializers
• DELETE /islandora/object/{id}/files/{fileId}
  • Delete a file for the entity in the route

Specific Files

We should have shortcuts to common file types, instead of needing to provide ids or go through the files list to find them. Basically just using the old DSIDs here.

• GET /islandora/object/{id}/files/obj
  • Retrieves the preservation master file for an entity
• GET /islandora/object/{id}/files/tn
  • Retrieves the thumbnail file for an entity
• GET /islandora/object/{id}/files/ocr
  • Retrieves the extracted text file for an entity
• GET /islandora/object/{id}/files/hocr
  • Retrieves the extracted text markup file for an entity
• GET /islandora/object/{id}/files/jp2
  • Retrieves the jp2 version of an image

Feedback would be nice.

[dannylamb]

I'm going to try and flesh this out a little more with actual expected responses and formats. Please feel free to add any comments in the meantime. If you think anything doesn't need to be there, or if I'm missing something, please let me know.

[dannylamb]

Closing. I'm tired of designing in a vacuum on this one, and we can't even seem to get past basic CRUD without getting derailed.

We'll do just enough for MVP to get by and revisit this in earnest at a later date with more community involvement.