Resource Not Found Error, Upload Link Provided in Error

[mmadson]

Hi,

I'm a HAL / vnd.error newbie and I'm just wondering if I have the hang of it.

I've got a resource

/configuration

It supports

PUT - create / overwrite the current configuration file
GET - retrieve the current configuration file

If a user attempts to GET before a PUT, I intend to return 404 NOT FOUND and I'd like to give some guidance in the response body for what the user should do. I was thinking of using vnd.error as my representation but I wanted to add a few helper links, like so:

{
    "_links": {
        "curies": [{
            "name": "term",
            "href": "/about/{term}",
            "templated": true
        }],
        "help": {
            "href": "/errors/configurationNotFound",
            "title": "Configuration Not Found Error Information"
        },
        "term:uploadConfiguration": {
            "href": "/configuration",
            "title": "Upload Configuration"
        },
        "term:errorCodes": {
            "href": "/errors/{errorCode}",          
            "title": "Error Code Detailed Information",
            "templated": true
        }
    },  
    "message": "The configuration was not found, did you forget to upload it?",
    "errorCode": "configurationNotFound"
}

Does this conform to the vnd.error spec? Is it valid HAL? ... or am I completely missing the mark. Thanks for the help!

[pnsantos]

Yes it's valid hal, however regarding vnd.error, as the spec is currently written you can't have an "errorCode" property (so note that the spec is not finalized), also not 100% sure if you can have curies in vnd.error links...

Just some unrelated comments:

• usually it's preferable to use full URLs instead of relative URLs
• you should really think about whether or not it's really usefull to have curies, the best they can bring you is make it easier for humans to read the messages, however probably 90% of the time machines (or libraries) will be parsing the contents, and in their case it's better not to have curies (it just complicates parsing. Any message size gains you have from curies can easily be offset from gzipping it.

[baldurrensch]

Yeah, I am with @pnsantos, I would avoid the currying. One thing you could also look into is using a templated URI (RFC-6570).