3SidesToEveryAPI - Revision history

78.43.162.114: /* Mine */

78.43.162.114 — Mon, 27 Aug 2012 05:56:25 GMT

Mine

←Older revision		Revision as of 05:56, 27 August 2012
Line 11:		Line 11:
	The other way to look at an [[API]] is from the point of its maintainer. For us, those who maintain some [[API]], this is the view through our own eyes. This is view is our daily bread. This is the view we get when we design our [[API]]s, document them, maintain them. As this is what we do day be day, we may start to believe that this is the most common view, that this is the most important one.		The other way to look at an [[API]] is from the point of its maintainer. For us, those who maintain some [[API]], this is the view through our own eyes. This is view is our daily bread. This is the view we get when we design our [[API]]s, document them, maintain them. As this is what we do day be day, we may start to believe that this is the most common view, that this is the most important one.

-	Indeed, as regular human beings, we'd like to see beauty around us. We want to feel more happy by writing nicer code. However keep in mind there is just one maintainer of an [[API]] and many users. As such when you need to decide whether make life simpler for us, or for our users, it should be a simple choice. This is actually the point of view presented in [[TheAPIBook]] and this is the reason why I often suggest that ''beauty does not matter'' - it does, but not the situation where an [[API]] maintainer refuses to simplify life of its [[API]] users because it would make his own code ''ugly''.	+	Indeed, as regular human beings, we'd like to see beauty around us. We want to feel more happy by writing nicer code. However keep in mind there is just one maintainer of an [[API]] and many users. As such when you need to decide whether make life simpler for us, or for our users, it should be a simple choice. This is actually the point of view presented in [[TheAPIBook]] and this is the reason why I often suggest that ''beauty does not matter'' - it does, but not in the situation where an [[API]] maintainer refuses to simplify life of its [[API]] users because it would make his own code ''ugly''.

	Good [[API]] is a facade over the internals of the [[API]] implementation. A nice facade can [[Cluelessness\|cluelessly]] hide all the mess and ugliness visible to the maintainer. It is just necessary to have maintainers willing to sacrifice, giving up on own desire to have ''beautiful'' code and not giving up on writing ''correct'' and ''reliable'' code. Because, beware, abstractions leak over facade. And as soon as unmaintainability leaks, even your users will not be able to write beautiful code. Which, obviously, can make them feel unhappy when struggling with the [[API]].		Good [[API]] is a facade over the internals of the [[API]] implementation. A nice facade can [[Cluelessness\|cluelessly]] hide all the mess and ugliness visible to the maintainer. It is just necessary to have maintainers willing to sacrifice, giving up on own desire to have ''beautiful'' code and not giving up on writing ''correct'' and ''reliable'' code. Because, beware, abstractions leak over facade. And as soon as unmaintainability leaks, even your users will not be able to write beautiful code. Which, obviously, can make them feel unhappy when struggling with the [[API]].

Apidesign: Reverted edits by Payton Robinson (Talk); changed back to last version by JaroslavTulach

Apidesign — Wed, 23 Nov 2011 08:03:12 GMT

Reverted edits by Payton Robinson (Talk); changed back to last version by JaroslavTulach

←Older revision		Revision as of 08:03, 23 November 2011
Line 43:		Line 43:

	[[Category:APITypes]] [[Category:Video]]		[[Category:APITypes]] [[Category:Video]]
-	~~[http://custom-essay-writing-service.org/index.php essay writing service]~~

Payton Robinson at 08:29, 22 November 2011

Payton Robinson — Tue, 22 Nov 2011 08:29:45 GMT

←Older revision		Revision as of 08:29, 22 November 2011
Line 43:		Line 43:

	[[Category:APITypes]] [[Category:Video]]		[[Category:APITypes]] [[Category:Video]]
		+	[http://custom-essay-writing-service.org/index.php essay writing service]

JaroslavTulach: /* Notes */

JaroslavTulach — Thu, 12 Aug 2010 12:30:33 GMT

Notes

←Older revision		Revision as of 12:30, 12 August 2010
Line 36:		Line 36:
	[[wikipedia::III_Sides_to_Every_Story\|musical albums]].		[[wikipedia::III_Sides_to_Every_Story\|musical albums]].

		+	{{#ev:youtube\|X6SYut3ruqI}}

-	[[Category:APITypes]]	+
		+
		+
		+
		+	[[Category:APITypes]] [[Category:Video]]

Apidesign: Reverted edits by Waexu (Talk); changed back to last version by JaroslavTulach

Apidesign — Sat, 24 Jul 2010 16:09:56 GMT

Reverted edits by Waexu (Talk); changed back to last version by JaroslavTulach

←Older revision		Revision as of 16:09, 24 July 2010
Line 36:		Line 36:
	[[wikipedia::III_Sides_to_Every_Story\|musical albums]].		[[wikipedia::III_Sides_to_Every_Story\|musical albums]].

-	~~[http://www.essaywriters.net freelance writing]~~

	[[Category:APITypes]]		[[Category:APITypes]]

Waexu at 10:06, 23 July 2010

Waexu — Fri, 23 Jul 2010 10:06:18 GMT

←Older revision		Revision as of 10:06, 23 July 2010
Line 36:		Line 36:
	[[wikipedia::III_Sides_to_Every_Story\|musical albums]].		[[wikipedia::III_Sides_to_Every_Story\|musical albums]].

		+	[http://www.essaywriters.net freelance writing]

	[[Category:APITypes]]		[[Category:APITypes]]

JaroslavTulach at 21:52, 24 November 2008

JaroslavTulach — Mon, 24 Nov 2008 21:52:05 GMT

←Older revision		Revision as of 21:52, 24 November 2008
Line 1:		Line 1:
	Not many things we know have just a single meaning. Often, depending on the point of view, there can be multiple [[3SidesOfAnyAPI\|truthful ways]] of describing properties of the same object. Throughout the [[TheAPIBook\|Practical API Design]] book I claimed beauty is not important, however after reading [[User:PetrHejl\|Petr Hejl]]'s recent blog post [[Blogs:PetrHejl:BeautyMatters\|Beauty Matters]], I can't do anything else then nod in agreement. Did I change my mind? Do I see why beauty matters in [[API]] design now? Well, maybe. But more importantly [[User:PetrHejl\|Petr]] made me realize that term [[API]] is not a single indivisible entity, it can probably have at least [[3SidesOfAnyAPI\|three different meanings]].		Not many things we know have just a single meaning. Often, depending on the point of view, there can be multiple [[3SidesOfAnyAPI\|truthful ways]] of describing properties of the same object. Throughout the [[TheAPIBook\|Practical API Design]] book I claimed beauty is not important, however after reading [[User:PetrHejl\|Petr Hejl]]'s recent blog post [[Blogs:PetrHejl:BeautyMatters\|Beauty Matters]], I can't do anything else then nod in agreement. Did I change my mind? Do I see why beauty matters in [[API]] design now? Well, maybe. But more importantly [[User:PetrHejl\|Petr]] made me realize that term [[API]] is not a single indivisible entity, it can probably have at least [[3SidesOfAnyAPI\|three different meanings]].
-
-	~~TBD: Geometrical point is indivisible, always the same. Line, divisible, but always same. API, is interface, a line, between at least two things, as such it should be as clear line!?~~

	== Yours ==		== Yours ==

JaroslavTulach: /* Notes */

JaroslavTulach — Mon, 24 Nov 2008 21:34:39 GMT

Notes

←Older revision		Revision as of 21:34, 24 November 2008
Line 27:		Line 27:
	== Notes ==		== Notes ==

-	[[Blogs:PetrHejl:BeautyMatters\|Beauty matters]] from ''~~yours~~'' perspective. Clients of ~~your~~ [[API]] need to be pleased, need to feel the beauty while using it. Only ~~them~~ they feel they are using [[Good Technology]].	+	[[Blogs:PetrHejl:BeautyMatters\|Beauty matters]] from ''Yours'' perspective. Clients of an [[API]] need to be pleased, need to feel the beauty while using it. Only then they feel they are using [[Good Technology]].

-	Beauty of ''Mine'' is unimportant to them. This is sad truth for the producers of an [[API]]. At a point when their application becomes widely used, they need to sacrifice themselves and ~~turn~~ from ~~the~~ artists creating beautiful [[API]]s into responsible maintainers of their [[Good Technology\|technology]].	+	Beauty of ''Mine'' is unimportant to them. This is a sad truth for the producers of an [[API]]. At a point when their application becomes widely used, they need to sacrifice themselves and change their role from being artists creating beautiful [[API]]s into responsible maintainers of their [[Good Technology\|technology]].

-	I'd argue that the [[API]] itself is beautiful, if it is real ''interface''. If it is the right tool for making its ''~~yours~~'' and ''~~mine~~'' sides co-exist smoothly.	+	I'd argue that the [[API]] itself is beautiful, if it is real ''interface''. If it is the right tool for making its ''Yours'' and ''Mine'' sides co-exist smoothly.
		+
		+	<comments/>

	PS: Maybe there is more than three ways to look at an API, but I am not aware of them right now and I could not resist to use this as a tribute to one of my favorite's		PS: Maybe there is more than three ways to look at an API, but I am not aware of them right now and I could not resist to use this as a tribute to one of my favorite's
	[[wikipedia::III_Sides_to_Every_Story\|musical albums]].		[[wikipedia::III_Sides_to_Every_Story\|musical albums]].

-	~~TBD:~~ Category:APITypes	+
		+	[[Category:APITypes]]

JaroslavTulach: /* The Truth */

JaroslavTulach — Mon, 24 Nov 2008 21:32:19 GMT

The Truth

←Older revision		Revision as of 21:32, 24 November 2008
Line 23:		Line 23:
	If we take this look, then the important part of [[API]] is the ''interface''. An interface is a thing between you and me, or among various actors, having their views. The [[Good Technology\|interface is good]] if it serves its role well. Which means, if it really separates the involved parties, yet it allows them to talk to each other. Can an [[API]] separate its user from the maintainer? Does it help the user to approach the application in the intended way? Does the [[API]] isolates actions taken by [[ClientAPI\|client calling into it]] from the life lived by [[ProviderAPI\|provider of the services]]?		If we take this look, then the important part of [[API]] is the ''interface''. An interface is a thing between you and me, or among various actors, having their views. The [[Good Technology\|interface is good]] if it serves its role well. Which means, if it really separates the involved parties, yet it allows them to talk to each other. Can an [[API]] separate its user from the maintainer? Does it help the user to approach the application in the intended way? Does the [[API]] isolates actions taken by [[ClientAPI\|client calling into it]] from the life lived by [[ProviderAPI\|provider of the services]]?

-	Many of these questions are objective, and can be evaluated without the need to ~~take~~ usurp a single point of view. As has been argued in [[Determining_What_Makes_a_Good_API\|Chapter 3]], all the properties of [[Good Technology]] may be present in an [[API]], without the necessity to make the [[API]] really beautiful. Definitely not from the maintainer's ''mine'' point of view.	+	Many of these questions are objective, and can be evaluated without the need to usurp a single point of view. As has been argued in [[Determining_What_Makes_a_Good_API\|Chapter 3]], all the properties of [[Good Technology]] may be present in an [[API]], without the necessity to make the [[API]] really beautiful. Definitely not from the maintainer's (e.g. ''mine'') point of view.

	== Notes ==		== Notes ==

JaroslavTulach: /* Mine */

JaroslavTulach — Mon, 24 Nov 2008 21:25:59 GMT

Mine

←Older revision		Revision as of 21:25, 24 November 2008
Line 14:		Line 14:

	Indeed, as regular human beings, we'd like to see beauty around us. We want to feel more happy by writing nicer code. However keep in mind there is just one maintainer of an [[API]] and many users. As such when you need to decide whether make life simpler for us, or for our users, it should be a simple choice. This is actually the point of view presented in [[TheAPIBook]] and this is the reason why I often suggest that ''beauty does not matter'' - it does, but not the situation where an [[API]] maintainer refuses to simplify life of its [[API]] users because it would make his own code ''ugly''.		Indeed, as regular human beings, we'd like to see beauty around us. We want to feel more happy by writing nicer code. However keep in mind there is just one maintainer of an [[API]] and many users. As such when you need to decide whether make life simpler for us, or for our users, it should be a simple choice. This is actually the point of view presented in [[TheAPIBook]] and this is the reason why I often suggest that ''beauty does not matter'' - it does, but not the situation where an [[API]] maintainer refuses to simplify life of its [[API]] users because it would make his own code ''ugly''.
		+
		+	Good [[API]] is a facade over the internals of the [[API]] implementation. A nice facade can [[Cluelessness\|cluelessly]] hide all the mess and ugliness visible to the maintainer. It is just necessary to have maintainers willing to sacrifice, giving up on own desire to have ''beautiful'' code and not giving up on writing ''correct'' and ''reliable'' code. Because, beware, abstractions leak over facade. And as soon as unmaintainability leaks, even your users will not be able to write beautiful code. Which, obviously, can make them feel unhappy when struggling with the [[API]].

	== The Truth ==		== The Truth ==