Now I am design a rest api, what makes me confusing is that the url case sensitive, for example, the /currentUser, I read some api design like google:
https://developers.google.com/oauthplayground/exchangeAuthCode
the named with camel case, and youtube:
https://www.youtube.com/youtubei/v1/log_event?alt=json&key=AIzaSyAO_FJ2SlqU8Q4STEHLGCilw_Y9_11qcW8
the named snake case, and stackoverflow:
https://stackoverflow.com/questions/71447875/is-casesensitive-important-for-appid
the named with a -. which is better? which one should I choose? or both are good, there is no need to consider the url case sensitive?
With respect to RFC 3986, URLs: /resourcename and /resourceName
are different. BUT: The general convention nowadays is to treat all URLs uniformly, regardless of character size.
Most REST APIs use hyphenated notation: /resource-name
Google is somewhat schizophrenic because it recommends something different here.
I recommend being case insensitive, using hyphens, and being consistent throughout the API.
Related
A question for this already exists, but is more tech focused and doesnt have answers: Representing a request body on HATEOAS link
I like HATEOAS. I love using it in my frontend to check if I can perform some actions by checking if a link exists instead of having business logic.
But what I do not understand is how HATEOAS can truly be useful in other scenario's. What if you have an "AddItemToBasket" link which would need a request body with some properties in it. The frontend would still need to know what this request body looks like. But HATEOAS doesn't tell you this.
This means you still have a dependency on API knowledge. I think lots of applications solve this problem with generated API clients/graphql, but that makes HATEOAS a hard sell.
Why use HATEOAS if we can't use the URL and http method, because it doesn't offer the full picture.
REST builds on standards (uniform interface constraint) and currently there is no standard way to do this. There is a Hydra W3C WorkGroup writing a standard about how to describe Hypermedia APIs. They use RDF, standard vocabs like schema.org and you can write your API specific vocab they call documentation. As far as I understand their model you can give parameters in the documentation for operations represented by hyperlinks. You can use for example XSD to add constraints like numbers, etc. to the parameters. It takes a lot more effort than normally to write this kind of formal documentation and as far as I understand there are currently no general REST clients which could profit from these, so it does not make much sense currently to write such an API, but it is possible if you want to.
As of why to use HATEOAS, it makes your API flexible and backward compatible. For example if somebody does not have permission for an operation, you simply don't send a hyperlink for it in the response. You can always add new operations and the existing clients don't have to support them, they can just focus on what they already know and they won't break because something extra is added. They don't have to know about the URI structures and the methods, which can freely change if the only thing they depend on is the operation type and the parameters.
I'm trying to follow best practices for an API, and I'm getting conflicting advice. Most suggest using spinal-case for URI (such as stackoverflow and RFC3986.
I have an API that allows filtering on GET requests by various parameters:
GET /endpoint?my-parameter=true
However, I also use the same parameter in GET responses and PATCH requests. There, I see a lot more camelCase or snake_case, and spinal-case is an extra with languages that don't allow hyphens in variable names. So I use this:
{
myParameter: true
}
This seems inconsistent. What's the best practice for handling these cases?
As Evert had said, there is no correct answer to this question.
spinal-case is ruled out because it is not usable with the basic syntax format in some languages like JavaScript.
Ex: response.user-name would break and it has to be written as response[“user-name”]
So, we are left with camelCase and snake_case. Out of these, I personally prefer the snake_case as it is more clear in differentiating the words than the camelCase.
So, It is completely your opinion on which one to use but make sure that you follow it in all your APIs.
Let's say I have an API to get a product given an product ID as: api/products/<productid>.
What would be a REST way to get relevant products given a product ID. I think I can use a query on the same endpoint as api/products?id=<productid>, but not sure if this is ideal or it might be confusing.
Standard practice for making api url is api/products/<productid>.
for params other than id (generally for filtering or searching purpose), query params are considered api/products?name=somename
The detailed resource naming guide can be found here
What would be REST way to get relevant resources?
Answer this question: how would you do it on the web?
You might have a web page for the product, and then a link from that page to a new page describing the related resources, where each entry in that page would include links to the product page of the specific resources.
What we need to define for the client (or make it easy to discover) is how to find the links.
In the case of the web, we are typically using HTML representation of our pages. HTML is special in that it has a standardized understanding of links. For human consumers, we surround the link with context (typically, the contents of the A element); for machines, we should be a bit more precise about defining the rule.
For representations that don't have a standardized understanding of links, we need to do something else. The most common answer is to use Web Linking, which is to say we put a description of the relationship between to URI into the headers of the response.
REST doesn't care what spelling conventions you use for your resource identifiers, so long as they are consistent with the production rules defined in RFC 3896. So you can choose any spelling convention you like.
For instance, it is common to use spelling conventions that include key value pairs in the query part of the URI, because HTML GET forms can be used to describe links with that shape, which simplifies certain use cases.
Since REST doesn't care about your spelling conventions, you can use the extra freedom to address other problems (what spellings are easy for people reading the logs? what spellings are easy for people documenting the API? and so on....)
How do we know which vocabulary/namespace to use to describe data with RDFa?
I have seen a lot of examples that use xmlns:dcterms="http://purl.org/dc/terms/" or xmlns:sioc="http://rdfs.org/sioc/ns#" then there is this video that uses FOAF vocabulary.
This is all pretty confusing and I am not sure what these vocabularies mean or what is best to use for the data I am describing. Is there some trick I am missing?
There are many vocabularies. And you could create your own, too, of course (but you probably shouldn’t before you checked possible alternatives).
You’d have to look for vocabularies for your specific needs, for example
by browsing and searching on http://lov.okfn.org/dataset/lov/ (they collect and index open vocabularies),
on W3C’s RDFa Core Initial Context (it lists vocabularies that have pre-defined prefixes for use with RDFa), or
by browsing through http://prefix.cc/ (it’s a lookup for typically used namespaces, but you might get an overview by that).
After some time you get to know the big/broad ones: Schema.org, Dublin Core, FOAF, RSS, SKOS, SIOC, vCard, DOAP, Open Graph, Ontology for Media Resources, GoodRelations, DBpedia Ontology, ….
The simplest thing is to check if schema.org covers your needs. Schema.org is backed by Google and the other major search engines and generally pretty awesome.
If it doesn't suit your needs, then enter a few of the terms you need into a vocabulary search engine. My recommendation is LOV.
Another option is to just ask the community about the best vocabularies for the specific domain you need to represent. A good place is answers.semanticweb.com, which is like StackOverflow but with more RDF experts hanging out.
Things have changed quite a bit since that video was posted. First, like Richard said, you should check if schema.org fits your needs. Personally when I need to describe something that's not covered on schema.org, I check LOV as well. If, and only if I can't find anything in LOV, I will then consider creating a new type or property. A quick way to do this is to use http://open.vocab.org/
A newer version of RDFa was published since that video was released: RDFa 1.1 and RDFa Lite. If you want to use schema.org only, I'd recommend to check http://www.w3.org/TR/rdfa-lite/
Vocabularies are usually domain specific. The xmlns line is deprecated. The RDFa profile at http://www.w3.org/profile/rdfa-1.1 lists the vocabularies available as part of initial context. Sometimes vocabularies may overlap in the context of your data. Analogous to solving math prb by either Algebraic or Geometric or other technique, mixing up vocabularies is fine. Equal terms can be found using http://sameas.org/ For addressing your consumer base's favoritism amongst vocab recognition, skos:closeMatch and skos:exactMatch may be used, eg. "gr:Brand skos:closeMatch owl:Thing" with any terms you please. Prefix attribute can be used with vocabularies besides those covered by initial context like: prefix="fb: http://ogp.me/ns/fb# vocab2: path2 ..." For cross-cutting concern across different domain vocabularies such as customizing presentation in search results microdata using schema.org guidelines should be beneficial. However, as this has nothing to do with specialization in any peculiar domain, prefixes are unavailable in this syntax. RDFa vocab have been helpful in such specific domain contexts that content seems to appeal further to participative audience while microdata targets those who've lost their way. For tasks that are too simple to merit full-fledged vocab, but have semantic implications, try http://microformats.org/ Interchanging usage of REST profile URIs for vocabs amongst the 3 syntaxes is valid, but useless owing to lack of affordable manpower to implement alternative support for the vocabs on the Web scale. How & why schema.org vocab merited separate microdata syntax of its own is discussed by Google employee Ian Hickson a. k. a. Hixie- the editor of WHATWG HTML5 draft at http://logbot.glob.com.au/?c=freenode%23whatwg&s=28+Nov+2012&e=28+Nov+2012#c747855 or http://krijnhoetmer.nl/irc-logs/whatwg/20121128#l-1122 If only Google had smart enough employees to implement parser for 1 syntax whose WG included its own employee also, then RDFa Lite inside RDFa would have been another course like Core Java within Java, & no need of separate microdata named mocking rip-off, but alas- our's is an imperfect world!
I want to understand RFC 2396 and the whole URL / URI thing better, and since NSURL from Cocoa is based on RFC 2396, I look for an overview. The RFC itself is too hard to read for me.
I'm going to assume that your real question is about the whole URI / URL / URN split. And I'll start by saying that it's just terminology, and in many cases they're interchangeable.
A URL is a Uniform Resource Locator: it identifies an access "scheme", such as http:, and contains enough information to locate that resource using that scheme. It doesn't necessarily contain enough information to access the resource: For example, an HTTP URL will get you to a page, but that page may have authentication requirements for access.
A URN is a Uniform Resource Name: it also starts with a "scheme", then contains arbitrary information appropriate for that scheme. URNs are confusing because, while there are several predefined schemes such as "uuid", there's no specified use for those schemes (unlike, say, HTTP). This is not necessarily a bad thing: I like to use URNs for things like XML Namespaces, where I don't want there to be any implication that you can actually retrieve something related to that namespace.
A URI is a Uniform Resource Identifier: a superset containing URLs, URNs, and a few other identifier types. The RFC mentions URLs and URNs, but doesn't go into a lot of detail. That's because it focuses on the physical construction of a URI (the general format, how it should be encoded, &c), not the usage.
Edit for the nitpickers: assume that when I say "starts with a scheme", there is the text "(which may be implied by current context)".
RFC 3305 might help:
This document [...] addresses and attempts to clarify issues pertaining to URIs. This document addresses how URI space is partitioned and the relationship between URIs, URLs, and URNs, describes how URI schemes and URN namespaces ids are registered, and presents recommendations for continued work on this subject.
For an overview, the abstract and the introduction of the actual RFC should be sufficient. You can pick specific sections of the RFC out that you want to understand better.
Basically, to understand RFC 2396 better or more thoroughly - which is what you are asking (as well as an overview..), you can't do much better than reading the RFC itself to be honest. Seems logical to me.