Introduce different api method for applications data requirement in the job overview screen

[villarin]

Api call: http://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/applications

This api method is currently used in two screens - applications and job overview screens.

The json output required varies in both cases - which causes the backend code to be more complex and harder to maintain.

So please dedicate a separate method for the application data requirement in the job overview page.

[pythondave]

I'm keen to make API discussions independent of any UI pages. I hope you
see the value in this.

The issue you raise here has more general implications, since the approach
I've taken in general in the API design intends exactly this.

For example, the idea (of the current API design approach) is that
http://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers
will
be used to get an array (a list) of teachers regardless of what information
is contained in each item of that array (for example,
0http://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers/0
has
different attributes to
1http://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers/1).
The idea is that
teachershttp://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers
will
be the only method which is ever used to get an array of teachers.

It could be then that we need to change the whole API design approach.

Again, it's probably best to pause here and check that we're on the same
wavelength.

I'd also be keen to understand more on the complexity of the back-end code
on various API design approaches we might take.

If this does boil down to being about the general API design approach, I
think this would be a good one to get together to work through.

On 9 July 2013 10:35, villarin notifications@github.com wrote:

Api call:
http://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/applications

This api method is currently used in two screens - applications and job
overview screens.

The json output required varies in both cases - which causes the backend
code to be more complex and harder to maintain.

So please dedicate a separate method for the application data requirement
in the job overview page.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/17
.

[villarin]

I follow you here - and when there is a common format to return results for
multiple API methods - I have no problem with the current approach.

However this method returns clearly differently formatted results based on
the filters provided...

And by combining multiple business functions in the backend - to satisfy the
current api access approach - The code becomes harder to read, test and
maintain.

[pythondave]

Understood - I think we're on the same wavelength.

Your reply indicates to me that we do in fact need to change the API design
approach.

In other words... we're going from (for example): Rule A)
teachershttp://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers
will be the only method which is ever used to get an array of teachers;
to: Rule B) teachershttp://pythondave.github.io/th-admin/2/0.4/scaffolding/api/default.html#/teachers
may
not always be the only method which is ever used to get an array of
teachers.

Rule A is currently part of my API design approach: it's a rule for me
which makes future API design clear-cut from my perspective.

If the consequences of Rule A make your life more complicated, then this is
very good reason to discuss this area, and in this case to potentially (and
probably) abandon Rule A.

If we do abandon Rule A, it's going to be useful to replace it with another
rule - or at the very least a guideline / set of guidelines.

This may come down to defining terms like "common format", "clearly
differently formatted results" and "business functions" more definitively.

Can you confirm that this make sense to you.

How about you have a go at proposing a replacement rule / guideline / set
of guidelines?

On 9 July 2013 14:46, villarin notifications@github.com wrote:

I follow you here - and when there is a common format to return results for
multiple API methods - I have no problem with the current approach.

However this method returns clearly differently formatted results based on
the filters provided...

And by combining multiple business functions in the backend - to satisfy
the
current api access approach - The code becomes harder to read, test and
maintain.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/17#issuecomment-20674602
.

[villarin]

Ok in my view there are two approaches we could take:

1. if we need to change API design - we could just use longer urls to
   satisfy different data requirements - for example:

/scaffolding/api/default.html#/teachers/list - used as a generic route to
retrieve teacher listings

/scaffolding/api/default.html#/teachers/application-summary - used to
retrieve teacher listings but also include additional information about
their application's for a particular job, as well as admin/school assessment
information.

1. We keep the current API design but organise the response message so we
   don't need new model classes for every request

In this case the following changes would help keep the backend code tidy:

2.1 query data - force statusId parameter to be always an array: So we would
use:

{statusIds:[1]} - if requesting
/scaffolding/api/default.html#/applications/0

OR

{statusIds:[2,3,4,5]} - if requesting
/scaffolding/api/default.html#/applications/1

2.2 Data returned:

Ensure teacher property has the same format regardless whether we request
/scaffolding/api/default.html#/applications/0 or
/scaffolding/api/default.html#/applications/1

"teacher": {"id": "437","fullName": "Kathleen Lunn", "avatarUrl":
"http://uifaces.com/faces/_twitter/nimaa_128.jpg", "profileUrl":
"/profile-url-external-to-the-dashboard/2491633", "score": 9, "adminNote":
"This is a unique admin note given to each"}

Note that score and adminNote are both unique to each candidate - this is
why I have suggested to keep adminNote as part of the teacher property.

Include "job" property in both requests - currently this is returned in
/scaffolding/api/default.html#/applications/0 but not in
/scaffolding/api/default.html#/applications/1 - Hence an additional service
call to: /scaffolding/api/default.html#/job/0 is needed to satisfy that data
requirement in the job overview screen.

Additional data:

This is the most tricky part for me...Different fields are returned in the
application requests:

For /scaffolding/api/default.html#/applications/0

"coverMessage", "dateApplied"

And for /scaffolding/api/default.html#/applications/1

"datePutForward": "2013-05-13T08:45:54.720Z", "statusId": 8, "statusDate":
"2013-06-06T01:24:30.377Z", "previousStatusId": 5, "adminNote",
"coverMessage", "schoolNote"

What I would suggest on this is that we reorganise the additional properties
as follows:

Leave field "coverMessage" intact - or as a single property in the response
for /scaffolding/api/default.html#/applications/0 and
/scaffolding/api/default.html#/applications/1 requests.

Add new property for "applicationStatus":[{"statusId":1, "date":
"2013-06-06T01:24:30.377Z "},{"statusId":3, "date":
"2013-06-06T01:25:30.377Z "},...] - This would contain the history of status
changes or could simply contain the last two statuses. However note that the
key factor here is encapsulating the application statuses values in a
property that can be easily populated
(/scaffolding/api/default.html#/applications/1) or not
(/scaffolding/api/default.html#/applications/0) in the api call result.

Add new property for "schoolData":{"note":"bla bla bla this is the school
note on the candidate for this application", "score": 3} - This would
contain the school note and score given to a candidate - as above this can
be easily populated or not based on whether the authenticated user is a
school or not.

Let me know your thoughts - if option 2 is feasible then I don't think we
would not need to change the api design approach.

[pythondave]

I need more time to digest this.

Can you let me know which of these you'd prefer me to prioritise:

A) this discussion
B) https://github.com/pythondave/th-admin/issues?milestone=1

Thanks!

[villarin]

Just add this one to the backlog.

The tasks in milestones 1 are blockers - hence they should take priority
over this.

[pythondave]

Okay - I'll continue to work on milestone 1 today.

Just so I get used to how you might use different terms...

1. Can you be clear on what you mean by 'backlog'... are you're referring
   to the product backlog or the sprint backlog?
2. Can you be clear on what you mean be 'blocker'.... i.e. what are the
   tasks in milestone 1 blocking from your perspective?

Once I understand those, I've a feeling we'll be able to make more use of
the milestone functionality to communicate these ideas more directly - but
let's see.

On 10 July 2013 07:29, villarin notifications@github.com wrote:

Just add this one to the backlog.

The tasks in milestones 1 are blockers - hence they should take priority
over this.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/17#issuecomment-20723937
.

[villarin]

1. Can you be clear on what you mean by 'backlog'... are you're referring
   to the product backlog or the sprint backlog?

For this task it would be the product backlog because it is not a blocker
(hence marked as enhancement) - The backlog generally contains well defined
tasks that you may work on but not at this stage. Once you are able to work
on them they are moved to an "In Progress" channel - or in the case you
could simply add them to a milestone.

1. Can you be clear on what you mean be 'blocker'.... i.e. what are the
   tasks in milestone 1 blocking from your perspective?

Blockers - In general any piece of functionality that does not work as
expected and blocks further works required to complete a feature. In this
case the tasks listed as bugs in milestones 1- or whatever prevents me from
seeing and verifying the outcome of the integration of the UI with the
backend.

[pythondave]

I've seen many of these terms used in many different ways, and I'm
therefore confused as to why some of your descriptions are so "absolute".

Are you referring to a specific methodology (with docs you can perhaps
point me to), or is this simply your experience of a specific methodology?

Just trying to understand...

On 10 July 2013 10:07, villarin notifications@github.com wrote:

1. Can you be clear on what you mean by 'backlog'... are you're referring
   to the product backlog or the sprint backlog?

For this task it would be the product backlog because it is not a blocker
(hence marked as enhancement) - The backlog generally contains well defined
tasks that you may work on but not at this stage. Once you are able to work
on them they are moved to an "In Progress" channel - or in the case you
could simply add them to a milestone.

1. Can you be clear on what you mean be 'blocker'.... i.e. what are the
   tasks in milestone 1 blocking from your perspective?

Blockers - In general any piece of functionality that does not work as
expected and blocks further works required to complete a feature. In this
case the tasks listed as bugs in milestones 1- or whatever prevents me from
seeing and verifying the outcome of the integration of the UI with the
backend.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/17#issuecomment-20729937
.

[villarin]

Yeap it is a SCRUM - just an implementation of the agile guidelines
approach.

To date I have used many of the agile driven PM systems because clients
differ a lot when it comes to adopting agile in the workplace - However to
me http://easybacklog.com/ is the one with far better results!

Have a look at their home page and FAQs and you will see how they draft
those concepts.

---

From: Ryan Randall [mailto:notifications@github.com]
Sent: 10 July 2013 10:38
To: pythondave/th-admin
Cc: villarin
Subject: Re: [th-admin] Introduce different api method for applications data
requirement in the job overview screen (#17)

I've seen many of these terms used in many different ways, and I'm
therefore confused as to why some of your descriptions are so "absolute".

Are you referring to a specific methodology (with docs you can perhaps
point me to), or is this simply your experience of a specific methodology?

Just trying to understand...

On 10 July 2013 10:07, villarin notifications@github.com wrote:

1. Can you be clear on what you mean by 'backlog'... are you're referring
   to the product backlog or the sprint backlog?

For this task it would be the product backlog because it is not a blocker
(hence marked as enhancement) - The backlog generally contains well
defined
tasks that you may work on but not at this stage. Once you are able to
work
on them they are moved to an "In Progress" channel - or in the case you
could simply add them to a milestone.

1. Can you be clear on what you mean be 'blocker'.... i.e. what are the
   tasks in milestone 1 blocking from your perspective?

Blockers - In general any piece of functionality that does not work as
expected and blocks further works required to complete a feature. In this
case the tasks listed as bugs in milestones 1- or whatever prevents me
from
seeing and verifying the outcome of the integration of the UI with the
backend.

Reply to this email directly or view it on
GitHub<#17 (comment)
7>
.

Reply to this email directly or view
#17 (comment) it
on GitHub.
<https://github.com/notifications/beacon/C6aQ2lOetMBBdndp2ctui2XMNl7L8XZXV9g
cDcLExCa5uSeprD3jcQNTHWsz4jKg.gif>

[pythondave]

To be clear... I've seen many of these terms used in many different ways --
even within SCRUM.

I'm sure you must've experienced the same if you've worked with lots of
different organisations. In fact, I've found that 2 people sitting next to
one another rarely have the same ideas as to what different things mean!

Anyway... I think this is why I find it hard to get my head around absolute
descriptions of things: I find it hard to reconcile an absolute with other
differing ideas I've experienced, and therefore it's hard for me to
understand. In other words, rather than "A is B", I'm much more comfortable
with "my understanding is that A is B" or "X defines A as B" or "I find
that things work well if we treat A as B". Styles like these feel far more
flexible and open to me.

That last sentence is important to me - I hope you can understand why.

Re http://easybacklog.com/ etc: if you create one or more some separate
threads for the issues this would address, I'll comment there. I've
cluttered this thread enough already!

On 10 July 2013 10:46, villarin notifications@github.com wrote:

Yeap it is a SCRUM - just an implementation of the agile guidelines
approach.

To date I have used many of the agile driven PM systems because clients
differ a lot when it comes to adopting agile in the workplace - However to
me http://easybacklog.com/ is the one with far better results!

Have a look at their home page and FAQs and you will see how they draft
those concepts.

---

From: Ryan Randall [mailto:notifications@github.com]
Sent: 10 July 2013 10:38
To: pythondave/th-admin
Cc: villarin
Subject: Re: [th-admin] Introduce different api method for applications
data
requirement in the job overview screen (#17)

I've seen many of these terms used in many different ways, and I'm
therefore confused as to why some of your descriptions are so "absolute".

Are you referring to a specific methodology (with docs you can perhaps
point me to), or is this simply your experience of a specific methodology?

Just trying to understand...

On 10 July 2013 10:07, villarin notifications@github.com wrote:

1. Can you be clear on what you mean by 'backlog'... are you're
   referring
   to the product backlog or the sprint backlog?

For this task it would be the product backlog because it is not a
blocker
(hence marked as enhancement) - The backlog generally contains well
defined
tasks that you may work on but not at this stage. Once you are able to
work
on them they are moved to an "In Progress" channel - or in the case you
could simply add them to a milestone.

1. Can you be clear on what you mean be 'blocker'.... i.e. what are the
   tasks in milestone 1 blocking from your perspective?

Blockers - In general any piece of functionality that does not work as
expected and blocks further works required to complete a feature. In
this
case the tasks listed as bugs in milestones 1- or whatever prevents me
from
seeing and verifying the outcome of the integration of the UI with the
backend.

Reply to this email directly or view it on
GitHub<
#17 (comment)
7>
.

Reply to this email directly or view
#17 (comment)
it
on GitHub.
<
https://github.com/notifications/beacon/C6aQ2lOetMBBdndp2ctui2XMNl7L8XZXV9g
cDcLExCa5uSeprD3jcQNTHWsz4jKg.gif>

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/17#issuecomment-20731816
.