Naming concepts

[Josep Blanquer]

All,

 

 As we're finishing up some refactoring of classes, I want to take this opportunity to ask for feedback around naming some concepts (and therefore how to name some base classes).

Let me do this in a proposal fashion this time, and work from there, rather than leaving it too open to change any existing name. So, I would like to propose the following names for the existing concepts of Praxis:

• MediaTypes : This is exactly what you think and know. They will be the classes describing the attributes of the exposed API resources and the views with which to render them.
• Endpoints  (or ApiEndpoints): These are the definitions describing how the API resources are exposed through the API. i.e. Actions, URL paths/verbs, api versions, parameters, headers payload, responses.....the whole nine yards etc.
  
• Controllers: Again, exactly what you think and already know. In Praxis Controllers are simple ruby objects that include the Controller module.

Now, the main difference in this proposal is the concept of "Endpoints", which we are currently calling "Resource Definitions". 

The main reason for bringing this up is that I'm not too thrilled about Resource Definitions name for a few of reasons:

1. It is pretty long, and using it in conversations seems to be confusing due to its term looseness.
   
2. The term "resource" is already used (especially if using the underlying Taylor gem) to refer to the "real" implementation of the underlying resources of the API. In other words, resources = business logic objects (i.e., the actual business code behind an API call). 
   
3. Since the default directory layout has a directory for each of the concepts above, this means that we need a "resource_definitions" directory. That feels pretty long too, and confusing if we wanted to have another "resources" directory (just for the bizlogic objects)

So, thinking about a new name, I could come up with Endpoints. They certainly get the vibe of something that is a "definition/description" and not a biz-logic implementation object. They are already associated with API paths, verbs, actions...etc. 

However, most of the time an endpoint is simply associated with a single "route". In Praxis and endpoint would refer to the complete set of routes (+actions+params+responses...) associated with all the things that one can do for a type of API resource. For example, the Blogs Endpoint, will define everything that you can do with Blogs through the API. There is precedence for such a grouping, though, in the common case of an API endpoint referring to the "base" of an API (i.e. the ec2 API endpoint). So in some senses you can think of an Endpoint as a "base" endpoint for an API resource.

So, anyway, I am not sure if this makes sense or not, and I am really not that thrilled about the name, but I don't really like 'resource definitions' either....I figured I would ask the list for opinions or other suggestions about the names before we firm it up for the first version of Praxis. Maybe somebody has a brilliant idea!

To put some more things into context, here's a hypothetical example of the default directory layout of an app following these conventions (for an app that fully uses the Taylor facilities):

• app/
  
• models (objects deriving from Taylor::Model or simple compatible PORO's)
• v1/
• media_types/ (objects derived from Praxis::MediaType)
• endpoints/  (objects including the Praxis::Endpoint module )
• controllers/ (objects including the Praxis::Controller module )
• resources/ (objects deriving from Taylor::Resource )

(An app is free to change all that, but providing a consistent and well known default goes a long way for most apps)

Thoughts?

Josep M.

[Lisa Watt]

I agree, that I don't like "Resource Definitions", as they confuse me with Taylor::Resource's.

I'm not sure I like endpoints, either, but I do not have anything better.

If we did go with Endpoints, I prefer ApiEndpoints. Just Endpoints makes me think of network endpoints.

--
You received this message because you are subscribed to the Google Groups "praxis-development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to praxis-developm...@googlegroups.com.
To post to this group, send email to praxis-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/praxis-development/CAA_K6YvzMjXwEwmLXDSsMBeFADD_pKaCXfuR5edtFG1UG3d9MA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Stephen Crosby]

Whatever we call it, this is the thing that a controller implements. Having the controller be the implementation of a resource definition seems fine to me and I prefer it to endpoint. I wouldn't spend much effort to avoid colliding with Taylor. Taylor is a separate project (not really our core concern), but what about 'ControllerDefinition'? It's even longer :) but it's even more clear.

To view this discussion on the web visit https://groups.google.com/d/msgid/praxis-development/CALDO-9AKiQvDiL7c_6RNDKWuph9G0Py2c_x0TSouNSC9Sjp8AA%40mail.gmail.com.

[jaso...@gmail.com]

So my $.02 on the naming structures in Praxis in general.

The whole media type concept still confuses me. Defining the attributes which a particular domain model may contain, seems to be getting grouped together with the concept of an actual response media type.

It seems to me that the "MediaTypes", currently are the resource definitions. And resources, are endpoints. -- I definitely second changing the name of resource to something like endpoint, or service, or "ServiceEndpoint" (think some people might get hung up on just service as they think of their application of the service and the individual "resources" as endpoints), as I don't think resource accurately describes what it is.

I think of resources as the data models themselves.

Ive been exploring the idea of building an SOA with praxis, and as Ive started digging into it, Ive been getting confused with these concepts.

I.E., ideally, I want to start out by declaring a bunch of ruby classes in a shared gem that represent all of the possible fields that the resources contain, namespaced by the service application that holds the resource. (so i can eventually set up service clients that can consume the services with an active record like api). But defining a "MediaType", and setting the attributes the data model contains, then setting the content type header in that media type, seems wrong. I mean, if I want a json representation as well as an xml representation, do you expect a completely separate "PostMediaTypeJson" and a "PostMediaTypeXml", or am I missing something?

It would make more sense to me to have a "PostsResource", which defines all of those attributes. But once again maybe I am missing something.

On Friday, July 25, 2014 12:23:28 AM UTC-6, Josep Blanquer wrote:
> All,
>  
>  As we're finishing up some refactoring of classes, I want to take this opportunity to ask for feedback around naming some concepts (and therefore how to name some base classes).
>
>
>
>
>
> Let me do this in a proposal fashion this time, and work from there, rather than leaving it too open to change any existing name. So, I would like to propose the following names for the existing concepts of Praxis:
>
>
>
>
>

> MediaTypes : This is exactly what you think and know. They will be the classes describing the attributes of the exposed API resources and the views with which to render them.Endpoints  (or ApiEndpoints): These are the definitions describing how the API resources are exposed through the API. i.e. Actions, URL paths/verbs, api versions, parameters, headers payload, responses.....the whole nine yards etc.

>
> Controllers: Again, exactly what you think and already know. In Praxis Controllers are simple ruby objects that include the Controller module.
>
>
> Now, the main difference in this proposal is the concept of "Endpoints", which we are currently calling "Resource Definitions". 
>
>
>
> The main reason for bringing this up is that I'm not too thrilled about Resource Definitions name for a few of reasons:
> It is pretty long, and using it in conversations seems to be confusing due to its term looseness.
>
> The term "resource" is already used (especially if using the underlying Taylor gem) to refer to the "real" implementation of the underlying resources of the API. In other words, resources = business logic objects (i.e., the actual business code behind an API call). 
>
> Since the default directory layout has a directory for each of the concepts above, this means that we need a "resource_definitions" directory. That feels pretty long too, and confusing if we wanted to have another "resources" directory (just for the bizlogic objects)
>
> So, thinking about a new name, I could come up with Endpoints. They certainly get the vibe of something that is a "definition/description" and not a biz-logic implementation object. They are already associated with API paths, verbs, actions...etc. 
>
>
>
> However, most of the time an endpoint is simply associated with a single "route". In Praxis and endpoint would refer to the complete set of routes (+actions+params+responses...) associated with all the things that one can do for a type of API resource. For example, the Blogs Endpoint, will define everything that you can do with Blogs through the API. There is precedence for such a grouping, though, in the common case of an API endpoint referring to the "base" of an API (i.e. the ec2 API endpoint). So in some senses you can think of an Endpoint as a "base" endpoint for an API resource.
>
>
>
> So, anyway, I am not sure if this makes sense or not, and I am really not that thrilled about the name, but I don't really like 'resource definitions' either....I figured I would ask the list for opinions or other suggestions about the names before we firm it up for the first version of Praxis. Maybe somebody has a brilliant idea!
>
>
>
> To put some more things into context, here's a hypothetical example of the default directory layout of an app following these conventions (for an app that fully uses the Taylor facilities):
>
> app/

> models (objects deriving from Taylor::Model or simple compatible PORO's)v1/media_types/ (objects derived from Praxis::MediaType)endpoints/  (objects including the Praxis::Endpoint module )
> controllers/ (objects including the Praxis::Controller module )resources/ (objects deriving from Taylor::Resource )