[Specifications] Specifying a list of resources of different types in `hydra:operation` `expects` field (#249)

visva-io has just created a new issue for https://github.com/HydraCG/Specifications:

== Specifying a list of resources of different types in `hydra:operation` `expects` field  ==
## Describe your API requirement

I need to be able to create multiple resources types in one HTTP POST for which a particular endpoint has been defined. We could make an analogy with a file system. Let’s say I have two kinds of resources: folders and files: I would like to be able to tell the client that I expect a list folders and files under a particular folder.



For example, with the endpoint `http://api.example.com/folders/`, which contains all resources of type `Folder`, I have defined a sub resource `tree` e.g. `http://api.example.com/folders/folderId/tree` which would allow to POST folders and files to be created under a specific folder instance.  

Now, I would like to be able to describe the operation in `Hydra` using something like this: 

```json
...
"operation": [        
 {            
  "method": "POST",            
  "title": "Files addition bulk operation",            
  "description": "Add a tree of resources under the target folder",
  "expects": [
   "http://api.example.com/classes/Folder",
   "http://api.example.com/classes/File",
  ]
 }    
]
```

which would simply list all requested files and folders to be able to create a file structure. In my particular scenario the user would need to provide a specific files structure known and provided by the API, we could imagine creating a Maven project with a predefined folders structure or something similar. The point of passing all this information is to be able, from the client perspective, to present everything the user needs to create in any way it wants, it could be a form with multiple sub-sections, or a wizard which would present all the information the user needs to provide once at a time.

What would be even better, is if I would be able to use SHACL to define all the requirements for form display, like here:
```json
"operation": [        
 {            
  "method": "POST",            
  "title": "Files addition bulk operation",            
  "description": "Add a tree of resources under the target folder",
  "expects": [
   {
    "@id" : "ex:Folder",
    "@type" : "NodeShape",
    "property" : [
     {
      "path" : "ex:name",
      "datatype" : "xsd:string" ,
      "pattern" : "^\\d{3}-\\d{2}-\\d{4}$"
     }
    ]
   },
   {
    "@id" : "ex:File",
    "@type" : "NodeShape",
    "property" : [
     {
      "path" : "ex:name",
      "datatype" : "xsd:string" ,
      "pattern" : "^\\d{3}-\\d{2}-\\d{4}$"
     },
     {
      "path" : "ex:data",
      "class" : "ex:Mpeg"
     }
    ]    
   }
  ]
 }    
]
```

This is a toy example with no real meaning but I think it describes the essential: I need to pass a list of different resources types to an endpoint to create multiple resources in one POST request. 

## Solution(s)

I considered defining a custom `rdf:Class`/`sh:NodeShape`  that would list all the required resources needed and just be pointed at by the operation `expects` field. This would work but, this is not really elegant as the hypermedia message should in my opinion be responsible for carrying this kind of information, not RDF. 

Thanks for your assistance,

Sébastien Hamel

P.S. Also, the [Hydra Console](https://www.markus-lanthaler.com/hydra/console/?url=http://www.markus-lanthaler.com/hydra/event-api/) does not seem to work at the moment, any plan to put it back online? 



Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/249 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Sunday, 17 September 2023 08:33:48 UTC