Re: [openstack-dev] [api] service type vs. project name for use in headers

[Brant Knudson]

On Wed, Jan 27, 2016 at 1:47 PM, michael mccune  wrote:

> hi all,
>
> there have been a few reviews recently where the issue of service type
> versus project name have come up for use in the headers. as usual this
> conversation can get quite murky as there are several good examples where
> service type alone is not sufficient (for example if a service exposes
> several api controllers), and as has been pointed out project name can also
> be problematic (for example projects can change name).
>
> i'm curious if we could come to a consensus regarding the use of service
> type *or* project name for headers. i propose leaving the ultimate decision
> up to the projects involved to choose the most appropriate identifier for
> their custom headers.
>
> i am not convinced that we would ever need to have a standard on how these
> names are chosen for the header values, or if we would even need to have
> header names that could be deduced. for me, it would be much better for the
> projects use an identifier that makes sense to them, *and* for each project
> to have good api documentation.
>
> so, instead of using examples where we have header names like
> "OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
> "OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.
>
> for reference, here are the current reviews that are circling around this
> issue:
>
> https://review.openstack.org/#/c/243429
> https://review.openstack.org/#/c/273158
> https://review.openstack.org/#/c/243414
>
> and one that has already been merged:
>
> https://review.openstack.org/#/c/196918
>
> thoughts?
>
>
Why does the service type or name need to be in the header at all? The
request goes to a specific service so the server and client already know
the service type or name. - Brant

regards,
> mike
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Sean Dague]

On 02/01/2016 09:13 AM, Brant Knudson wrote:
> 
> 
> On Wed, Jan 27, 2016 at 1:47 PM, michael mccune  > wrote:
> 
> hi all,
> 
> there have been a few reviews recently where the issue of service
> type versus project name have come up for use in the headers. as
> usual this conversation can get quite murky as there are several
> good examples where service type alone is not sufficient (for
> example if a service exposes several api controllers), and as has
> been pointed out project name can also be problematic (for example
> projects can change name).
> 
> i'm curious if we could come to a consensus regarding the use of
> service type *or* project name for headers. i propose leaving the
> ultimate decision up to the projects involved to choose the most
> appropriate identifier for their custom headers.
> 
> i am not convinced that we would ever need to have a standard on how
> these names are chosen for the header values, or if we would even
> need to have header names that could be deduced. for me, it would be
> much better for the projects use an identifier that makes sense to
> them, *and* for each project to have good api documentation.
> 
> so, instead of using examples where we have header names like
> "OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
> "OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.
> 
> for reference, here are the current reviews that are circling around
> this issue:
> 
> https://review.openstack.org/#/c/243429
> https://review.openstack.org/#/c/273158
> https://review.openstack.org/#/c/243414
> 
> and one that has already been merged:
> 
> https://review.openstack.org/#/c/196918
> 
> thoughts?
> 
> 
> Why does the service type or name need to be in the header at all? The
> request goes to a specific service so the server and client already know
> the service type or name. - Brant

Sometimes it does. But some times we have one service return ref links
to another url, which might be in a different service.

A very common instance is Nova returning links to glance images, which
include a glance image url directly.

Keeping that header in place is extremely helpful from a clarity
perspective instead of using heuristics of manually splitting apart urls
and guessing. That second approach is one of the reasons the devstack
keystone v3 patches keep being disruptive.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Ken'ichi Ohmichi]

2016-01-28 5:37 GMT+09:00 Ryan Brown :
>>
>> I think we would be better served in selecting these things thinking
>> about the API consumers first.  We already have  enough for them to wade
>> through, the API-WG is making great gains in herding those particular
>> cats, I would hate to see giving back some of that here.
>>
>> so, instead of using examples where we have header names like
>> "OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
>> "OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our
>> guideline.
>>
>>
>> I think the listed reviews have it right, only referencing service
>> type.  We have attempted to reduce the visible surface area of project
>> names in a LOT of areas, I do not think this is one that needs to be an
>> exception to that.
>
>
> +1, I prefer service type over project name. Among other benefits, it leaves
> room for multiple implementations without being totally baffling to
> consumers.

+1 from me.
We are working for microversions testing on Tempest side now, and the
testing framework can be useful for all projects which implement
microversions mechanism.
In our idea, each project will pass service_type to the testing
framework and Tempest will send a request with the microversion header
which contains the service_type.
If the guideline doesn't clarify service_type or project_name, the
implementation ways of Tempest are different between projects and
users/developers are confused when implementing new tests.
I am feeling the guideline is for avoiding this kind of situation.

As cdent said on previous mail, the api-wg guideline is just best
practice, not rule.
That seems just a recommendation, so it is nice to clarify it from our
experience.

Thanks
Ken Ohmichi

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Mike Perez]

On 10:55 Jan 28, Kevin L. Mitchell wrote:
> On Thu, 2016-01-28 at 11:06 +, Chris Dent wrote:
> > I think it is high time we resolve the question of whether the
> > api-wg guidelines are evaluating existing behaviors in OpenStack and
> > blessing the best or providing aspirational guidelines of practices
> > which are considered best at a more universal level.
> 
> From my historical perspective, the API WG had essentially two phases,
> with only the first phase getting general support at the time: 1. trying
> to document existing practices and recommend best practices; 2.
> establishing rules that all OpenStack APIs must adhere to.  I think the
> first phase is essentially complete at this point, but I think Chris is
> right that it's high time to decide whether the guidelines are normative
> or informative…and my vote would be for normative, and with a focus on
> the API consumer.  After all, an API is useless if it's a pain to use :)

+1

So I see TC members commenting on this thread. I think it would be great to
have the TC members discuss this, but I know they're going to want consensus
from projects.

Projects under the big tent hopefully have some representation with the API
working group at this point [1].

It would be great if said group could actually begin this conversation with
their respected project team and understand if any of these guidelines [2] are
not being followed, and collect that information to understand where we're at
today.

I'm sure what this thread is raising is just one of the things, but right now
it's a big unknown to us where we all are currently today, and will continue to
block us from making a big decision like this.

[1] - http://specs.openstack.org/openstack/api-wg/liaisons.html
[2] - https://specs.openstack.org/openstack/api-wg/

-- 
Mike Perez

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Kevin L. Mitchell]

On Thu, 2016-01-28 at 11:06 +, Chris Dent wrote:
> I think it is high time we resolve the question of whether the
> api-wg guidelines are evaluating existing behaviors in OpenStack and
> blessing the best or providing aspirational guidelines of practices
> which are considered best at a more universal level.

From my historical perspective, the API WG had essentially two phases,
with only the first phase getting general support at the time: 1. trying
to document existing practices and recommend best practices; 2.
establishing rules that all OpenStack APIs must adhere to.  I think the
first phase is essentially complete at this point, but I think Chris is
right that it's high time to decide whether the guidelines are normative
or informative…and my vote would be for normative, and with a focus on
the API consumer.  After all, an API is useless if it's a pain to use :)
-- 
Kevin L. Mitchell 
Rackspace


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Jay Pipes]

On 01/27/2016 08:31 PM, Dean Troyer wrote:

On Wed, Jan 27, 2016 at 1:47 PM, michael mccune > wrote:

i am not convinced that we would ever need to have a standard on how
these names are chosen for the header values, or if we would even
need to have header names that could be deduced. for me, it would be
much better for the projects use an identifier that makes sense to
them, *and* for each project to have good api documentation.


I think we would be better served in selecting these things thinking
about the API consumers first.  We already have  enough for them to wade
through, the API-WG is making great gains in herding those particular
cats, I would hate to see giving back some of that here.


Amen.


so, instead of using examples where we have header names like
"OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
"OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.

I think the listed reviews have it right, only referencing service
type.  We have attempted to reduce the visible surface area of project
names in a LOT of areas, I do not think this is one that needs to be an
exception to that.

Projects will do what they are going to do, sometimes in spite of
guidelines.  This does not mean that the guidelines need to bend to
match that practice when it is at odds with larger concerns.

In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.


+100.

-jay

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Jay Pipes]

Couldn't agree more, Chris.

-jay

On 01/28/2016 11:06 AM, Chris Dent wrote:

On Wed, 27 Jan 2016, Dean Troyer wrote:


I think we would be better served in selecting these things thinking
about
the API consumers first.  We already have  enough for them to wade
through,
the API-WG is making great gains in herding those particular cats, I
would
hate to see giving back some of that here.


I think it is high time we resolve the question of whether the
api-wg guidelines are evaluating existing behaviors in OpenStack and
blessing the best or providing aspirational guidelines of practices
which are considered best at a more universal level.

Within the group many of our debates pivot around the above issue.
There is some fear that if we choose the latter none of the
guidelines will be followed.

I think that's pretty weak sauce and we need to take both a more
assertive and more aggressive stance with regard to achieving
quality and consistency in the APIs[1]. Reaching consistency is the
primary mission of the group but consistent crap is still crap and
our API consumers deserve better.

The thread about Ekko which has spawned a subthread about the
collision between the ceilometer and monasca APIs should be a
good learning moment™: Having some rigor and vision in our
guidelines would allow us to state things like:

* The APIs are services (for which there could potentially be other
   implementations but the service represents a namespace)
* Identifiers used in that service are service related, not project
   related.
* More specifically: URIs are signifiers of a service, not a project.

The guidelines should be one (of several) ways in which a project
can ask itself "are we being OpenStack?". If there is a collision
with the guidelines, that provides a clue that the thing being
considered is out of alignment. It should be an excuse to change or
create new guidelines.


In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.


For the specific issue of the headers, I think the above is the crux of
the biscuit. The service catalog is intended to be a source of truth;
that truth should be reflected in the guidelines. If the API being
considered isn't (planned to be) in the service catalog does that
API need to even be thinking about adhering to OpenStack guidelines?

[1] Choosing to be more rigorous in the guidelines puts a large
burden on the group to not simply rubberstamp incoming guidelines
and also be more selective about what actually matters in terms of
the guidelines. This is challenging because it became clear early on
that adherence to correct HTTP in existing APIs was weak and there
was an opportunity for the group to be a fount of knowledge and
wisdom and distill best practices.

That work still needs to go on, but it is also time to align
the work with some of the main themes in today's OpenStack:

* alignment with the service catalog and what it is trying to
   accomplish
* effective use of APIs when re-using real users' client code amongst a
   diversity of clouds

Just those two things can help us evaluate proposals with some
useful constraints.



__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Chris Dent]

On Wed, 27 Jan 2016, Dean Troyer wrote:


I think we would be better served in selecting these things thinking about
the API consumers first.  We already have  enough for them to wade through,
the API-WG is making great gains in herding those particular cats, I would
hate to see giving back some of that here.


I think it is high time we resolve the question of whether the
api-wg guidelines are evaluating existing behaviors in OpenStack and
blessing the best or providing aspirational guidelines of practices
which are considered best at a more universal level.

Within the group many of our debates pivot around the above issue.
There is some fear that if we choose the latter none of the
guidelines will be followed.

I think that's pretty weak sauce and we need to take both a more
assertive and more aggressive stance with regard to achieving
quality and consistency in the APIs[1]. Reaching consistency is the
primary mission of the group but consistent crap is still crap and
our API consumers deserve better.

The thread about Ekko which has spawned a subthread about the
collision between the ceilometer and monasca APIs should be a
good learning moment™: Having some rigor and vision in our
guidelines would allow us to state things like:

* The APIs are services (for which there could potentially be other
  implementations but the service represents a namespace)
* Identifiers used in that service are service related, not project
  related.
* More specifically: URIs are signifiers of a service, not a project.

The guidelines should be one (of several) ways in which a project
can ask itself "are we being OpenStack?". If there is a collision
with the guidelines, that provides a clue that the thing being
considered is out of alignment. It should be an excuse to change or
create new guidelines.


In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.


For the specific issue of the headers, I think the above is the crux of
the biscuit. The service catalog is intended to be a source of truth;
that truth should be reflected in the guidelines. If the API being
considered isn't (planned to be) in the service catalog does that
API need to even be thinking about adhering to OpenStack guidelines?

[1] Choosing to be more rigorous in the guidelines puts a large
burden on the group to not simply rubberstamp incoming guidelines
and also be more selective about what actually matters in terms of
the guidelines. This is challenging because it became clear early on
that adherence to correct HTTP in existing APIs was weak and there
was an opportunity for the group to be a fount of knowledge and
wisdom and distill best practices.

That work still needs to go on, but it is also time to align
the work with some of the main themes in today's OpenStack:

* alignment with the service catalog and what it is trying to
  accomplish
* effective use of APIs when re-using real users' client code amongst a
  diversity of clouds

Just those two things can help us evaluate proposals with some
useful constraints.

--
Chris Dent   (╯°□°)╯︵┻━┻http://anticdent.org/
freenode: cdent tw: @anticdent__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Alex Meade]

I'd like an answer on this specific issue. I agree with Chris and I wonder
if our goal is consistency across services or an ideal standard.

Nova has 'X-OpenStack-Nova-API-Version' and Manila has
'X-Openstack-Manila-Api-Version'. If we deviate from this, we should
suggest that those projects add the new standard as an alternative way to
specify the version.

Cinder has this patch, https://review.openstack.org/#/c/224910/, which
tries to be consistent with Nova and Manila. If we don't decide on the
guideline soon it will likely merge soon as to not impede progress.

-Alex

On Thu, Jan 28, 2016 at 6:32 AM, Jay Pipes  wrote:

> Couldn't agree more, Chris.
>
> -jay
>
>
> On 01/28/2016 11:06 AM, Chris Dent wrote:
>
>> On Wed, 27 Jan 2016, Dean Troyer wrote:
>>
>> I think we would be better served in selecting these things thinking
>>> about
>>> the API consumers first.  We already have  enough for them to wade
>>> through,
>>> the API-WG is making great gains in herding those particular cats, I
>>> would
>>> hate to see giving back some of that here.
>>>
>>
>> I think it is high time we resolve the question of whether the
>> api-wg guidelines are evaluating existing behaviors in OpenStack and
>> blessing the best or providing aspirational guidelines of practices
>> which are considered best at a more universal level.
>>
>> Within the group many of our debates pivot around the above issue.
>> There is some fear that if we choose the latter none of the
>> guidelines will be followed.
>>
>> I think that's pretty weak sauce and we need to take both a more
>> assertive and more aggressive stance with regard to achieving
>> quality and consistency in the APIs[1]. Reaching consistency is the
>> primary mission of the group but consistent crap is still crap and
>> our API consumers deserve better.
>>
>> The thread about Ekko which has spawned a subthread about the
>> collision between the ceilometer and monasca APIs should be a
>> good learning moment™: Having some rigor and vision in our
>> guidelines would allow us to state things like:
>>
>> * The APIs are services (for which there could potentially be other
>>implementations but the service represents a namespace)
>> * Identifiers used in that service are service related, not project
>>related.
>> * More specifically: URIs are signifiers of a service, not a project.
>>
>> The guidelines should be one (of several) ways in which a project
>> can ask itself "are we being OpenStack?". If there is a collision
>> with the guidelines, that provides a clue that the thing being
>> considered is out of alignment. It should be an excuse to change or
>> create new guidelines.
>>
>> In this case, the use of service type as the primary identifier for
>>> endpoints and API services is well established, and is how the service
>>> catalog has and will always work.
>>>
>>
>> For the specific issue of the headers, I think the above is the crux of
>> the biscuit. The service catalog is intended to be a source of truth;
>> that truth should be reflected in the guidelines. If the API being
>> considered isn't (planned to be) in the service catalog does that
>> API need to even be thinking about adhering to OpenStack guidelines?
>>
>> [1] Choosing to be more rigorous in the guidelines puts a large
>> burden on the group to not simply rubberstamp incoming guidelines
>> and also be more selective about what actually matters in terms of
>> the guidelines. This is challenging because it became clear early on
>> that adherence to correct HTTP in existing APIs was weak and there
>> was an opportunity for the group to be a fount of knowledge and
>> wisdom and distill best practices.
>>
>> That work still needs to go on, but it is also time to align
>> the work with some of the main themes in today's OpenStack:
>>
>> * alignment with the service catalog and what it is trying to
>>accomplish
>> * effective use of APIs when re-using real users' client code amongst a
>>diversity of clouds
>>
>> Just those two things can help us evaluate proposals with some
>> useful constraints.
>>
>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[michael mccune]

On 01/28/2016 06:32 AM, Jay Pipes wrote:

Couldn't agree more, Chris.

-jay

On 01/28/2016 11:06 AM, Chris Dent wrote:

On Wed, 27 Jan 2016, Dean Troyer wrote:


I think we would be better served in selecting these things thinking
about
the API consumers first.  We already have  enough for them to wade
through,
the API-WG is making great gains in herding those particular cats, I
would
hate to see giving back some of that here.


I think it is high time we resolve the question of whether the
api-wg guidelines are evaluating existing behaviors in OpenStack and
blessing the best or providing aspirational guidelines of practices
which are considered best at a more universal level.

Within the group many of our debates pivot around the above issue.
There is some fear that if we choose the latter none of the
guidelines will be followed.

I think that's pretty weak sauce and we need to take both a more
assertive and more aggressive stance with regard to achieving
quality and consistency in the APIs[1]. Reaching consistency is the
primary mission of the group but consistent crap is still crap and
our API consumers deserve better.

The thread about Ekko which has spawned a subthread about the
collision between the ceilometer and monasca APIs should be a
good learning moment™: Having some rigor and vision in our
guidelines would allow us to state things like:

* The APIs are services (for which there could potentially be other
   implementations but the service represents a namespace)
* Identifiers used in that service are service related, not project
   related.
* More specifically: URIs are signifiers of a service, not a project.

The guidelines should be one (of several) ways in which a project
can ask itself "are we being OpenStack?". If there is a collision
with the guidelines, that provides a clue that the thing being
considered is out of alignment. It should be an excuse to change or
create new guidelines.


In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.


For the specific issue of the headers, I think the above is the crux of
the biscuit. The service catalog is intended to be a source of truth;
that truth should be reflected in the guidelines. If the API being
considered isn't (planned to be) in the service catalog does that
API need to even be thinking about adhering to OpenStack guidelines?

[1] Choosing to be more rigorous in the guidelines puts a large
burden on the group to not simply rubberstamp incoming guidelines
and also be more selective about what actually matters in terms of
the guidelines. This is challenging because it became clear early on
that adherence to correct HTTP in existing APIs was weak and there
was an opportunity for the group to be a fount of knowledge and
wisdom and distill best practices.

That work still needs to go on, but it is also time to align
the work with some of the main themes in today's OpenStack:

* alignment with the service catalog and what it is trying to
   accomplish
* effective use of APIs when re-using real users' client code amongst a
   diversity of clouds

Just those two things can help us evaluate proposals with some
useful constraints.


i agree as well Chris, and well said.

thanks to everyone for commenting on this issue. i agree with the 
sentiments that are being voiced here, and i think the arguments for 
sticking to service type make a good deal of sense.


my main concern was that there had been some pushback on the idea of 
service type for headers. i like the notion that we are hewing closer to 
the service catalog ideals, that makes good sense to me. i just wanted 
to leave room for projects to make their own path if necessary, i guess 
this option is always there by default.


again, thanks for the insights. i will back off my concerns on the 
outstanding reviews based on this issue, and work towards helping us 
stay closer to service type for the guidelines.


regards,
mike


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Ravi, Goutham]

What is the point of the guideline if we're not able to influence some of the 
biggest projects out there, that would keep growing with what they have..

Maybe we should add a note in each of those guidelines saying some examples 
exist where SERVICE_TYPE has been replaced by PROJECT_NAME for these headers; 
however, this "anomaly" is only where projects have/support multiple 
controllers, under different SERVICE_TYPEs. It should be explicit that 
guidelines recommend SERVICE_TYPE (as Dean stated) and do not recommend the 
PROJECT_NAME; and that the main purpose of inclusion of these names at all is 
to distinguish the headers when they are being recorded for some support 
purposes, etc; amongst all the OpenStack REST API calls.

--
Goutham



From: Dean Troyer <dtro...@gmail.com<mailto:dtro...@gmail.com>>
Reply-To: "OpenStack Development Mailing List (not for usage questions)" 
<openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>>
Date: Wednesday, January 27, 2016 at 3:31 PM
To: "OpenStack Development Mailing List (not for usage questions)" 
<openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>>
Subject: Re: [openstack-dev] [api] service type vs. project name for use in 
headers

On Wed, Jan 27, 2016 at 1:47 PM, michael mccune 
<m...@redhat.com<mailto:m...@redhat.com>> wrote:
i am not convinced that we would ever need to have a standard on how these 
names are chosen for the header values, or if we would even need to have header 
names that could be deduced. for me, it would be much better for the projects 
use an identifier that makes sense to them, *and* for each project to have good 
api documentation.

I think we would be better served in selecting these things thinking about the 
API consumers first.  We already have  enough for them to wade through, the 
API-WG is making great gains in herding those particular cats, I would hate to 
see giving back some of that here.

so, instead of using examples where we have header names like 
"OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest 
"OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.

I think the listed reviews have it right, only referencing service type.  We 
have attempted to reduce the visible surface area of project names in a LOT of 
areas, I do not think this is one that needs to be an exception to that.

Projects will do what they are going to do, sometimes in spite of guidelines.  
This does not mean that the guidelines need to bend to match that practice when 
it is at odds with larger concerns.

In this case, the use of service type as the primary identifier for endpoints 
and API services is well established, and is how the service catalog has and 
will always work.

dt

--

Dean Troyer
dtro...@gmail.com<mailto:dtro...@gmail.com>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Dean Troyer]

On Wed, Jan 27, 2016 at 1:47 PM, michael mccune  wrote:

> i am not convinced that we would ever need to have a standard on how these
> names are chosen for the header values, or if we would even need to have
> header names that could be deduced. for me, it would be much better for the
> projects use an identifier that makes sense to them, *and* for each project
> to have good api documentation.
>

I think we would be better served in selecting these things thinking about
the API consumers first.  We already have  enough for them to wade through,
the API-WG is making great gains in herding those particular cats, I would
hate to see giving back some of that here.


> so, instead of using examples where we have header names like
> "OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
> "OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.
>

I think the listed reviews have it right, only referencing service type.
We have attempted to reduce the visible surface area of project names in a
LOT of areas, I do not think this is one that needs to be an exception to
that.

Projects will do what they are going to do, sometimes in spite of
guidelines.  This does not mean that the guidelines need to bend to match
that practice when it is at odds with larger concerns.

In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.

dt

-- 

Dean Troyer
dtro...@gmail.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] service type vs. project name for use in headers

[michael mccune]

hi all,

there have been a few reviews recently where the issue of service type 
versus project name have come up for use in the headers. as usual this 
conversation can get quite murky as there are several good examples 
where service type alone is not sufficient (for example if a service 
exposes several api controllers), and as has been pointed out project 
name can also be problematic (for example projects can change name).


i'm curious if we could come to a consensus regarding the use of service 
type *or* project name for headers. i propose leaving the ultimate 
decision up to the projects involved to choose the most appropriate 
identifier for their custom headers.


i am not convinced that we would ever need to have a standard on how 
these names are chosen for the header values, or if we would even need 
to have header names that could be deduced. for me, it would be much 
better for the projects use an identifier that makes sense to them, 
*and* for each project to have good api documentation.


so, instead of using examples where we have header names like 
"OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest 
"OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.


for reference, here are the current reviews that are circling around 
this issue:


https://review.openstack.org/#/c/243429
https://review.openstack.org/#/c/273158
https://review.openstack.org/#/c/243414

and one that has already been merged:

https://review.openstack.org/#/c/196918

thoughts?

regards,
mike

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] service type vs. project name for use in headers

[Ryan Brown]

On 01/27/2016 03:31 PM, Dean Troyer wrote:

On Wed, Jan 27, 2016 at 1:47 PM, michael mccune > wrote:

i am not convinced that we would ever need to have a standard on how
these names are chosen for the header values, or if we would even
need to have header names that could be deduced. for me, it would be
much better for the projects use an identifier that makes sense to
them, *and* for each project to have good api documentation.


I think we would be better served in selecting these things thinking
about the API consumers first.  We already have  enough for them to wade
through, the API-WG is making great gains in herding those particular
cats, I would hate to see giving back some of that here.

so, instead of using examples where we have header names like
"OpenStack-Some-[SERVICE_TYPE]-Header", maybe we should suggest
"OpenStack-Some-[SERVICE_TYPE or PROJECT_NAME]-Header" as our guideline.


I think the listed reviews have it right, only referencing service
type.  We have attempted to reduce the visible surface area of project
names in a LOT of areas, I do not think this is one that needs to be an
exception to that.


+1, I prefer service type over project name. Among other benefits, it 
leaves room for multiple implementations without being totally baffling 
to consumers.



Projects will do what they are going to do, sometimes in spite of
guidelines.  This does not mean that the guidelines need to bend to
match that practice when it is at odds with larger concerns.

In this case, the use of service type as the primary identifier for
endpoints and API services is well established, and is how the service
catalog has and will always work.

dt


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev