|
Caveat: I don't have enough experience in this area to be qualified to pass judgment.
When consuming someone's API, I prefer explicitness. So, I think I like your approach of "getServiceFee".
However, that's a property of some larger entity, so I could certainly see the argument that one should just get the entity and look for ServiceFee within that. That scales; as new properties are added, the API has to change in the method you're describing.
As to the plural versus the singular, the author's examples give it away: to get the collection, you use plural; but then tacking on an id gives you companies/xxx, which returns a single company and seems clumsy.
I suspect the answer is just pick one and be consistent. I guess I prefer the pluralized version slightly, because it's more like this is a search API: get me all companies which qualify under the provided parameters (or lack thereof). I might even argue that companies/XXX should return a collection, even though we certainly expect only one to qualify, because it is a search.
But my lack of experience in this area probably means I'm filtering through the wrong lens.
|
|
|
|
|
|
Singular vs Plural is todays Tabs vs Spaces war. Both are correct for different reasons. I (we) tend to stay with singular unless there is a compelling reason to go plural. Primarily due to how some words pluralize (Person vs People).
This was an extremely lightweight article. The problem set is broader. Like, you have /populace endpoint. Do you return 300 million results or paginate the results? You need to incorporate security aspects. Do you have access to ALL the /populace (as a federal agency), or only some (as a state/province agency)? Even then, do you have access to all the data within a populace resource or only a limited set?
The problem I often see is thinking of the REST API like a programming API. It is not. If you go that way, you are building a RPC, and will have scaling issues at some point. You have to step back and really think resource. getServiceFee is communicative, but so is GET /serviceFee. But /serviceFee is not a "resource". It is part of a larger resource. Depending on access rights, it might be one of only a few elements available in the returned resource.
A better, simplified article is https://dzone.com/articles/5-basic-rest-api-design-guidelines[^]. It covers some of these points. A better collection of articles is https://dzone.com/articles/rest-api-best-practices-with-design-examples-from[^]. Sticking to these best practices helps open up some other frameworks to assist in building and documenting your API.
Bottom line, good REST is not simple or easy. It takes a lot of up front effort and then discipline to implement well. Even with that said, I (we) still got it wrong multiple times. Just less disasterously. 
The cure to boredom is curiosity. There is no cure for curiosity. -- Dorothy Parker
modified 24-Dec-19 13:05pm.
|
|
|
|
|
Not only did tomales randomly get delivered to us last night (it happens), I finished Parsley in record time, and it is COOL tech, if wildly underappreciated.
Slang is so neat. I totally wanted to build a parser generator with code in the grammars that could work in any final language. It's here.
I love that it's working in the wild.
Next I may add backtracking support. If that works maybe I'll try to rebuild Slang's parser with it.
I'm just tickled. So much winning today.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
|
Today is as devoid of thermal excitation as the dextro-mamamry of a female necromancer. *
* I may have Leslied myself - but the day started at about -10C and windy with serious gusts off the ocean @ roughly 60-65 k/h
| Ravings en masse^ |
|---|
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "If you are searching for perfection in others, then you seek disappointment. If you seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
You forgot the enormous copper and zinc alloy lingerie.
|
|
|
|
|
I have to do so much processing to the codedom just to get VB to choke it down.
Why? The language is STUPID. That's why. There's no more succinct and accurate way to put it.
The grammar is stupid.
The runtime is stupid.
The language overall, is stupid.
You have two different equality operators you have to use depending on whether you're comparing reference types or value types. Because of that I have to visit every damned == and != in the tree, do type resolution on both sides of the expression (slow) and then based on that determine whether I should say "=" or "is"
Stupid.
You have to explicitly name your public implementation types for a method. So if i want to implement IEnumerator<t>.Current I have to also have Implements IEnumerable(of T)
This means for every public method you declare i have to go through all the base types of its declaring class, resolving each one (slow) to see if it matches the method signature (slow) of the declared method, so i can add Implements.
Stupid.
And don't get me started on the bugs in the VB codedom
It has taken me 2 hours just to fix all that crap
 Angry honey.
/rant
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
honey the codewitch wrote: You have two different equality operators you have to use depending on whether you're comparing reference types or value types.
Not quite.
You use Is to compare for reference equality, and = to use the overloaded equality operator. But unlike C#, VB.NET won't fall back to using reference equality if the equality operator hasn't been overloaded.
Reference type vs value type is irrelevant, other than the fact that reference equality for value types will always be False.
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
That's not what the compiler told me but okay. I don't trust it either.
Anyway, I'm doing ValueType checks now and it works.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
|
Sure, but the example you gave has no way to compare equality.
The closest thing you could do would be like Equals() or ReferenceEquals() at that point, and honestly i'm not sure how those will behave exactly on such a struct though i imagine ReferenceEquals() ends up comparing the stack pointers or something. I think Equals() would just forward basically to ReferenceEquals() in that case.
The other possibility is equals does a memberwise compare. That's about 50/50 likely but on such a struct they would always be equal since they have no fields. Hmmm
I'd have to research it all to be sure, but it gives me something to think about and look into.
Although it would be nice for VB to manufacture a way to do equality checks on such a structure, it's not very useful in practice. I wonder if i don't mind breaking in that case?
Considering that case uses = it gives you the opportunity to fix by overloading=
Unfortunately, you cannot overload operators in slang because CodeDOM won't render operator overloads.  but you can overload a class that it references the binary of.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
honey the codewitch wrote: I wonder if i don't mind breaking in that case?
Probably a sensible option - C# won't let you use == on a struct which doesn't implement an equality operator either.
You're right about ReferenceEquals, which obviously wouldn't work for value types.
The default Equals implementation for a value type uses reflection to compare the value of all of the fields:
Reference Source[^]
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
Richard Deeming wrote: The default Equals implementation for a value type uses reflection to compare the value of all of the fields:
Reference Source[^]
Aha. I remember reading that years ago. It does a memberwise compare, using Reflection.
Ugly.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
Easy: Simply ignore VB 
It does not solve my Problem, but it answers my question
modified 19-Jan-21 21:04pm.
|
|
|
|
|
I'd love to honestly. It's not a "real" language AFAIAC. However, the CodeDOM dictates target languages. I don't. The fact is, despite me complaining about VB there are probably N other languages like Python that have weird quirks so I really did need to correct for all this (except for the bugs in VBCodeProvider) for my stuff to work as advertised with all languages - or at least all languages that support a reasonable amount of the CodeDOM
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
So your complaint isn't about VB itself. It's about a buggy code generator.
|
|
|
|
|
That's pretty much my opinion of C# too, except for the details.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
I don't know. C# grew on me. I look at the grammar of it as like a serious subset of C++, with some sugar added so you don't have to worry about . vs. ->
although latter versions like C#8 are getting ugly.
Still, my main gripe with C# is lack of source level templates and lack of multiple inheritance, but especially the templates. Generics just don't cut it. You can't do things like partial template specializations or traits with generics.
I come from a C++ background but these days I code in C# a lot. I like the fact that it's "cheaper" in terms of effort and debugging than C++. It's like if Java were something I could stand. Which is nice.
Although I'll add, while the grammar is simple, it's highly ambiguous and requires extensive type information in order to parse it. That really bugs me. My parser has to do serious backtracking and then i spend ages in CPU cycles fixing the parsetree i get back by injecting type information into it and correcting it based on that. It's nasty.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
|
Yes, I know it's heresy, but that's what I dislike so much about it. There is far too much going on under the hood for my tastes.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
I don't mind that it wraps so many things. I mind that there's no way to get at stuff without it. Less of a problem in VB.NET then VB6, admittedly.
Edit: I lost the plot. You were talking about C#. I get what you mean, with anonymous methods and iterators awaitable methods and such it can be really difficult to know what's going on.
But you don't *have* to use that stuff. I could say the same honestly about STL with C++. There's way too much voodoo happening for my tastes. But it's the game.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
modified 19-Dec-19 17:39pm.
|
|
|
|
|
Rick York wrote: That's pretty much my opinion of C# too
Booooo! Hisssss! 
So what language DO you prefer?
|
|
|
|
|
Quote: Booooo! Hisssss!
Yeah! That's telling him. How dare he? 
|
|
|
|
|
Why would you support VB?
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
It's more principle than anything. I want to support as many languages as possible. Actually supporting VB makes that possible because of how much work it was.
When I was growin' up, I was the smartest kid I knew. Maybe that was just because I didn't know that many kids. All I know is now I feel the opposite.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
![Java | [Coffee]](https://www.codeproject.com/script/Forums/Images/coffee.gif)
