self-describing messages

2020-01-23b.js

/*
  who does it better?
*/

// this
{
  "rel" : "http://example.org/vocabularies/customer-communiations#customers/update-name-and-sms"
  "href" : "http://example.org/customers/123"
  "type" : "..."
}

// or this
{
  "rel" : "update-name-and-sms"
  "href" : "http://example.org/customers/123"
  "type" : "..."
}

// or maybe
{
  "update-name-and-sms" : "http://example.org/customers/123"
  "type" : "..."
}

2020-02-23.js

/* 
  title: "self-describing" -- what does that mean?
  author: mamund
  date: 2020-01-23
*/

// what does this describe?
{"link" : "http://example.org/customers/123"}

// or this?
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
}

// or maybe:
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
  "method" : "put"
}

// or...
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
  "method" : "put"
  "properties" : [
    {"name" : "", "sms" : "" }
  ]
}
   
// but even...      
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
  "method" : "put"
  "contentType" : "application/x-www-form-urlencoded",
  "properties" : [
    {"name" : "", "sms" : "" }
  ]
}
    
// also...
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
  "method" : "put"
  "contentType" : "application/x-www-form-urlencoded",
  "accepts" : "application/json",
  "properties" : [
    {"name" : "", "sms" : "" }
  ]
}
  
// and possibly...
{
  "rel" : "update", 
  "href" : "http://example.org/customers/123" 
  "method" : "put"
  "contentType" : "application/x-www-form-urlencoded",
  "accepts" : "application/json",
  "properties" : [
    {"param" : "name", "value" : "", "required" : true},
    {"param" : "sms", "value" : "", "required" : false, "regex: "^[0-9]" }
  ]
}
  
/*
 and, yes. they all describe the *same thing*.  but some describe better, more fully, then others.
 
 if you could not acess this API's documentation and could not reach any support/developer staff, 
 which description would you want to see when attempting to use this API successfully?
*/