Thoughts on a substructure...

[Bruno Watt]

Hey Everybody! LTLFTC

I'm working through an implementation using MASON2 at the moment to develop a uniform interface, I'm making good progress and am playing with some of the minutia and am looking to sanity check some thinking I have.

I will use the 'notification' payload to demonstrate the question I presently have. I am building, shock horror, a social style app and there are many different types of notifications that a user may receive. Here is a snip of a notification payload:

....  
  "id": "n001",
  "dateCreated": "2014-12-17T20:09:53Z",
  "dateViewed": null,
  "dateFollowed": null,
  "message": {
    "id": "m001",
    "sender": "Tom Habiford",
    "title": "Gurgs!",
    "digest": "Hey gurgich, you are not very bright!",
    "dateSent": "2014-12-17T20:09:53Z",
    "@controls": {
      "is:follow": {
        "type": "link",
        "rel": "follow",
        "href": "http://.../messages/m001",
        "method": "GET",
        "title": "link to this message record"
      },
      "is:image": {
        "type": "image/png",
        "rel": "image",
        "href": "http://.../messages/m001/thumb",
        "method": "GET",
        "title": "link to thumbnail associated with this message"
      }
    }
  }
.....

Now in this case the notification relates to a new message that the user has received, other alternative notifications can be for an upcoming event that the user follows, a user following this user or a request to enter into a contract has been received....

In my first naive implementation I have just used the "message" object inside the root of the message.

In an earlier attempt I had created a substructure to hold the details of what the notification was about, including a field that stated the type of notification. I'm thinking this is probably the best way to go, that way the client just needs to look at whatever is inside that substructure and not know what to look for in the root.

So this leads me to think that perhaps this is the best solution (change in red):

"id": "n001",
  "dateCreated": "2014-12-17T20:09:53Z",
  "dateViewed": null,
  "dateFollowed": null,

  "source": {
     "message": {
       "id": "m001",
       "sender": "Tom Habiford",
       "title": "Gurgs!",
       "digest": "Hey gurgich, you are not very bright!",
       "dateSent": "2014-12-17T20:09:53Z",
       "@controls": {
         "is:follow": {
           "type": "link",
           "rel": "follow",
           "href": "http://.../messages/m001",
           "method": "GET",
           "title": "link to message record"
         },
         "is:image": {
           "type": "image/png",
           "href": "http://.../messages/m001/thumb",
           "method": "GET",
           "title": "link to thumbnail for account associated with message"
         }
       }

     }
  }

I think I'll use a different semantic descriptor than 'source' but you get the idea. To me this makes sense, anytime you get a notification (notifications can make one and only one notification) all you need to do is look inside the source object and you have everything you need to know.

So I guess I am just sanity checking here, my question is is there any reason NOT to nest the target of the notification i.e.: is there a reason why it would be better in the root, I cannot think of any.

Any input is welcome.

Thanks folks.

B

[Jørn Wildt]

My personal preference would be to have a "source" property as you suggest in the second JSON example. But having "message" inside that could be an issue ... what if the source was an event? Would you then have an "event" property inside? How would the client know what to look for?

What about this which is a bit more like classic OO-style inheritance (the source can be a message, an event or something else that "inherits" from some sort of source-base-class:

{

  "id": ...,

  "source":

  {

    "type": "message",

    "title", "...",

    ... other message specific properties ...

  }

}

/Jørn

--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Bruno Watt]

Hi Jørn,

Thanks for your reply. You may have stumbled on my biggest misunderstanding of the media type that we were kind of touching on in our discussion about rel's.

The example you have given above is exactly how my solution worked before I started to add substructures with control elements.

Allow me to expand on my reasoning a little using a different part of my specification a gig (please shoot holes if you see them). A gig has an artist, an event and a promoter, it can also be part of a tour (but doesn't have to be) and a few other things. To avoid having very specific link relations like "event-promoter" I have used the semantic descriptors as the keys for these substructures, for example

 "dateCreated": "2014-12-17T20:09:53Z",

 "id": "g001",
 "title": "delProfundo Jackin Thursdays, Tall trees 2015-10-14",
 "startDateTime": "2015-10-14T22:00:00",
 "duration": "2.5",
 "rate": "100",
 "fixed": "0",
 "currency": "USD",
 "appendix": "this is a giant string for riders and conditions",
 "promoter": {
   "id": "u002",
   "title": "Bill Hobbs",
   "@controls": {
     "self": {
       "type": "link",
       "href": "http://.../users/u002",
       "method": "GET",
       "title": "link to the promoter of the event this gig associates with"

     },
     "is:image": {
       "type": "image/png",

       "href": "http://.../users/u002/thumb",
       "method": "GET",
       "title": "link to the promoter users thumbnail"
     }
   }
 },
 "venue": {
   "id": "v001",
   "title": "Tall Trees",
   "@controls": {
     "self": {
     "type": "link",
     "href": "http://.../venues/v001",
     "method": "GET",
     "title": "link to the venue associated with the event"

   },
   "is:image": {
     "type": "image/png",

     "href": "http://.../venues/v001/thumb",
     "method": "GET",
     "title": "link to venue thumbnail"
     }
   }
 },
 "event": {
   "id": "e001",
   "title": "Jackin' Thursdays",
   "@controls": {
     "self": {
     "type": "link",
     "href": "http://.../events/e001",
     "method": "GET",
     "title": "link to the associated event"

   },
   "is:image": {
     "type": "image/png",

     "href": "http://.../events/e001/thumb",
     "method": "GET",
     "title": "link to thumbnail for event"
     }
   }
 },

So you can see that I have substructures here (promoter, event, venue), allowing the use of more generic rel's. My expectation was to describe the relationship between these structures in the ALPS profile that I am developing now (so "message" is presently missing its currie notation).

My thinking is in doing it this way,when looking inside the "source" structure by knowing the profile then the client will know that a notification can contain substructures of "message", "event", "gig", "friend" etc and that any time any of these exist inside the substructure then the localised "self" link will always point to that record (essentially the substructure is an element the same as that in a collection view).

There is a secondary reason for my thinking on this, some of the contract negotiation processes that exist in most of the apps I've been playing with tend to reuse the contents of these substructures over and over again, passing them encapsulated seems sensible to me.

I know I've not really asked a question here but I am curious as to your (and anyones) thinking on my reasoning, and any holes you can shoot in my understanding would be very helpful. I actually have some other questions about how I'm structuring things but I will come back to them in another thread.

Cheers,

B

[Jørn Wildt]

From my point of view this seems to be the crux:

> My thinking is in doing it this way,when looking inside the "source" structure by knowing the profile then the client will know that a notification can contain substructures of "message", "event", "gig", "friend" etc and that any time any of these exist inside the substructure then the localised "self" link will always point to that record (essentially the substructure is an element the same as that in a collection view).

So the notification substructure "source" contains one or many different substructures like "message", "event", or "gig" and so on? Does that mean all of these are simultaneous sources of the notification? That seems slightly odd to me - I would only expect only a single entity to be the source of a notification? That entity could then contain related information like for instance what "gig" an event is part of.

But it sure does make sense to use "localized" "self" links in the substructures - that is what I have been doing too. Maybe I would call them "scoped" "self" links as the name of the substructure defines the scope of the "self" link.

If I understand you correct (which I probably don't ...) I would go for something like this where the source *is a* something (message/event/other) and the source then contains the substructure relevant to it:

{

  "id": ...,

  "source":

  {

    "type": "message",

    "title", "...",

    ... other message specific properties ...,

    "venue":

    {

      ... venue specific details ...

    },

    "promotor":

    {

      ... promotor specific details ...

    }

  }

}

[Bruno Watt]

Ah! Ok I see what you are saying. 

So the notification substructure "source" contains one or many different substructures like "message", "event", or "gig" and so on? Does that mean all of these are simultaneous sources of the notification? ...

In the case of the notification payload your hunch is correct, the notification will only ever carry one of these types of things at a time. Other representations however may carry a few of them.

 As is a theme across my posts I am trying to keep as much commonality to structures as possible. This is  why I have that nested structure (as stated I had it originally the way you are suggesting) each of the substructures here are identical to those that may be present in offers, gigs, tours, slots and a few other things.

Ok you've almost convinced me....but :) .....lets go back to your original objection, being how would a client know what to expect. So...

1) From your perspective does the inclusion of an ALPS profile solve this?

2) If so what is the crux of the remainder of the issue? Is it style or is there something else that you think could be a problem?

If its only style then to me it becomes a toss up between that extra level and not reusing structures that already exist. I'm probably splitting hairs here but i'm curious. :)

--
You received this message because you are subscribed to a topic in the Google Groups "Mason media type" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/mason-media-type/8Vgnj4s4Q8g/unsubscribe.
To unsubscribe from this group and all its topics, send an email to mason-media-ty...@googlegroups.com.

[Jørn Wildt]

> 1) From your perspective does the inclusion of an ALPS profile solve this?

No idea. I haven't worked with ALPS (or other profile frameworks). But if the client is given some sort of knowledge (profile/namespace/type-id/whatever) about the payload then I would expect it to know what substructures to look for.

I do not see any profile information in your payloads - how does the client know what the profile of the response is?

> 2) If so what is the crux of the remainder of the issue? Is it style or is there something else that you think could be a problem?

Sorry, this is where "design by e-mail" breaks down - I don't know what to say here. Hopefully you have enough input to make an intelligent decision by now :-)

/Jørn

[Bruno Watt]

haha understood, yes I can keep moving.

On the ALPS profile no there is no reference to it in the payloads as yet, as I'm working alone on this generating the payloads helps me work through the state design process so I've only just moved on to machine documentation. As I vaguely eluded to earlier the structures like message haven't been prefixed with their curie notation yet.

So I have

  "@namespaces": {

      "is": {

          "name": "http://.../rels#"

      },

    "profile": {

          "name": "http://.../giggrinder#"

  },

in the payload. so gig should be "profile:gig" or whatever i shorten it to.

I've only just started on the profiles ALPS is one of Mike's drafts. He walks through it in "RESTful web API's", which is a very good read. Heres a wee snip:

{

  "alps": {

    "version": "1.0",

    "doc": {

      "href": "http://.../doc.html"

    },

    "descriptor": [

      {

        "id": "gig",

        "type": "semantic",

        "doc": {

          "value": "A single booked performance belonging to an Artist and Event"

        },

        "descriptor": [

          {

            "href": "#title"

          },

          {

            "href": "#startDateTime"

          }

        ]

      },

      {

        "id": "title",

        "type": "semantic",

        "doc": {

          "value": "common name for any record's title"

        }

      },

      {

        "id": "startDateTime",

        "type": "semantic",

        "doc": {

          "value": "common starting date/time in ISO8601 Zulu format"

        }}]}}

needs the transitions too, also references back to the documentation but its all coming along :)

thanks for your input, I really appreciate the help.

till next time!

b

[Bruno Watt]

Just by way of closing this our Jørn I thought I would come back and eat some humble pie.

I WAS going to go with my way but then late last night realised that what I was doing with the objects I wanted to reuse was stupid. Why I didn't have them in an array to begin with boggles the mind.

Anyhoo I'm using the approach you agreed with now and have encapsulated the objects that may or may not be present in other representations as an array of anonymous objects and the source of the notification (like those anon objects) now has a type parameter<facepalm>

So my continuity issue is solved and things look nice. Back to finishing my profile!

:)

...