am using Jena, Java to generate RDF statements. I want to know if there are rules I need to follow to generate resolvable URIs.
I think you're talking about what is now referred to as linked data, and yes, there are patterns you should follow. At its simplest, you should (i) use http: URI's, (ii) ensure that those URI's refer to locations in a web space you control, and (iii) ensure that an HTTP GET request to those URI's, with an appropriate mime type, will result in machine-readable representations of the resources they denote.
Related
We have an HTTP application which needs to communicate to the user the path of the resource the user has requested or modified, as people otherwise struggle to later locate the corresponding file when accessing the backing storage through other means (e.g. remote shell to a host where said storage is mounted with known path prefix).
For example, the user agent would send a HTTP request with the following first line:
PUT /project/human-genome/files/meetings/owners-101190/report.txt
...meaning someone requested creation and storage of the resource at the corresponding URL.
Now, you can say one should be trivially able to infer the file path from the URL, and normally I'd be inclined to design URLs with such assumption in mind, but in our case we don't generally have such relationship that the client can automatically infer the path like that, and this relationship (the "mapping", if you will) can change, so what we have is this additional level of indirection, you can say, that makes assumptions like this inapplicable.
In practice, it means the above URL can't be assumed to correspond to a file named report.txt stored in some folder with path like /project/human-genome/files/meetings/owners-....
Instead, we want to have the client be able to negotiate obtaining the path value related to the resource.
I have thought of the following solutions:
Return the path with a response header for at least HEAD requests; the header is probably custom, something like Resource-Path; If utilizing a custom header, there needs to be specification that tells for what responses related to the resource, the header is returned? Is it only returned for HEAD requests? Doesn't that fly in the face of HTTP basically describing HEAD request as GET-without-response-body, meaning that the corresponding GET response also shall include the response header? That is an overhead and a waste if the client didn't need the metadata. And if metadata is returned, how much of it, and what kind of representation of it? This option intuitively seems to be inferior to the second alternative:
Allocate a dedicated URL for metadata about the resource including the "stored path", e.g. /metadata/project/human-genome/files/meetings/owners-101190/report.txt, with optional suffix like :path or /path and/or utilizing URL query variables -- to specify what metadata to return; whether it's some /metadata/ URL pathname prefix, or some /metadata or :metadata suffix, this seems more "idiomatic", but I am not entirely convinced of the wisdom in representing also metadata as server resource -- what would the semantics for requests like PUT .../metadata, be?
On top of the choices above, I am half-suspecting this is a solved problem and there is some RFC I should read that solves this very problem -- surely metadata about resources that doesn't fall into categories for which HTTP uses response headers (which normally pertain to the response, not the resource), is something a lot of applications and application servers routinely have to manage?
Is there a truly idiomatic approach here that can be the correct answer to this problem?
I am confused here! I read a blog and it said in RESTful architecture,we can use more than one URI to represent a resource.
Is this right,since URI is use as identifier,it should be unique. Did I misunderstand something?
Sorry I am not going to post the link of that post because it is written in Chinese:)
Yes that is true. REST follows existing standards (aka. uniform interface constraint), now we are talking about the URI standard.
I think the simplest example about this is localhost. So imagine you have a REST service on http://localhost/api on your computer. Now by default you can reach the same service using http://127.0.0.1/api. So even the api root does not have an 1:1 relationship with the URIs in this case. In terms of the URI standard uniqueness means an 1:n relation between the resource and the URIs. This is different to the uniqueness term you are used to by relational databases. So in different words, a single resource can be identified by multiple URIs, but a single URI can identify only a single resource.
They do in this and probably any other website, but I'm not sure I understand why.
A popular analogy compares RESTful resources to files in the file system and filename users wouldn't point to the same object as filename users/ static web pages and in a static website users would point to users.html and users/ - to a different file - users/index.html.
Short answer: they may only identify the same resource if one redirects to the other.
URI's identify resources, but they do so differently depending on the response status code to a GET request in HTTP. If one returns a 3xx to the other, then the two URI's identify the same resource. If the two resources each return a 2xx code, then the URI's identify different resources. They may return the same response in reply to a GET request, but they are not therefore the same resource. The two resources may even map to the same handler to produce their reply, but they are not therefore the same resource. To quote Roy Fielding:
The resource is not the storage object. The resource is not a
mechanism that the server uses to handle the storage object. The
resource is a conceptual mapping -- the server receives the identifier
(which identifies the mapping) and applies it to its current mapping
implementation (usually a combination of collection-specific deep tree
traversal and/or hash tables) to find the currently responsible
handler implementation and the handler implementation then selects the
appropriate action+response based on the request content.
So, should /users and /users/ return the same response? No. If one does not redirect to the other, then they should return different responses. However, this is not itself a constraint of REST. It is a constraint, however, which makes networked systems more scalable: information that is duplicated in multiple resources can get out of sync (especially in the presence of caches, which are a constraint of REST) and lead to race conditions. See Pat Helland's Apostate's Opinion for a complete discussion.
Finally, clients may break when attempting to resolve references relative to the given URI. The URI spec makes it clear that resolving the relative reference Jerry/age against /users/ results in /users/Jerry/age, while resolving it against /users (no trailing slash) results in /Jerry/age. It's amazing how much client code has been written to detect and correct the latter to behave like the former (and not always successfully).
For any collection (which /users/ often is), I find it best to always emit /users/ in URI's, redirect /users to /users/ every time, and serve the final response from the /users/ resource: this keeps entities from getting out of sync and makes relative resolution a snap on any client.
filename users wouldn't point to the same object as filename users/.
That is not true. In most filesystems, you cannot have a file named users and a directory named users in the same parent directory.
cd users and cd users/ have the same result.
There are some nuances on this, while "users" represent one resource while "users/" should represent a set of resources, or operations on all resources "users"... But there does not seem to exist a "standard" for this issue.
There is another discussion on this, take a look here: https://softwareengineering.stackexchange.com/questions/186959/trailing-slash-in-restful-api
Technically they are not the same. But a request for /users will probably cause a redirect to /users/ which makes them semantically equal.
In terms of JAX-RS #Path, they can both be used for the same path.
what is the best way to support zeroconf names in the location segment of a URI design?
RFC 3986 (Uniform Resource Identifier (URI): Generic Syntax) makes no mention of zeroconf and i fear the URI syntax is not designed to work beyond DNS resolution.
the ideal answer syntax will:
conform to the generic URI syntax
handle zeroconf names with multi-byte characters
Here are some options:
dnssd://local/_printer._tcp/Fancy printer/
dnssd://Fancy printer._printer._tcp.local
These strings are IRIs, not URIs, in order to address i18n issues.
a nested URI is another approach that is backward compatible. a nested URI defines the location for use with discovery protocols like zeroconf.
see 'nested uniform resource identifiers' manuel urena and david larrabeiti
however i dont find evidence this approach in is wide use.
A universal resource identifier is a generic way to locate a resource. For internationalization, you may want to check on IRI, which is almost the same, but allows for full Unicode compatibility. The reason that it doesn't mention Zeroconf is that URI is a generalized protocol. Zeroconf may use URIs are part of its protocol for discovery, but URI will never use specific implementation in its protocol (you won't find ftp:, https:, mailto:, skype: etc in there either)
Zeroconf is a protocol to automatically configure your network and discover available services. It consists of three parts, address selection (part of IPv4/6), name resolution (mDNS) and service discovery (UPnP (Microsoft), DNS-SD (Apple)). Modern operating systems support all of this out of the box.
If we take UPnP, the discovery is done based on a URI, iirc. The returned information is given in XML. XML can be any Unicode encoding. If you're a device driver manufacturer, you can place any character in there. The final phase may be presentation, which is a URL but that's optional.
A URI / URL both support internationalized characters, but only escaped and not in the domain name part.
-- Abel --
I am designing a REST service and am trying to weight the pros and cons of using the full array of http verbs and content negotiation vs GET string variables. Does my choice affect cacheability? Neither solution may be right for every area.
Which is best for the crud and queries (e.g. ?action=PUT)?
Which is best for api version picking (e.g. ?version=1.0)?
Which is best for return data type(e.g. ?type=json)?
CRUD/Queries are best represented with HTTP verbs. A create and update is usually a PUT or POST. A retrieve would be a GET. Deletes would be a DELETE. Thats the generally mapping. The main point is that a GET doesn't cause side effects, and that the verbs do what you'd expect them to do.
Putting the action in the URI is OK if thats the -only- way to pass it (e.g, the http client library doesn't allow you to send non-GET/POST requests). Most libraries do, though, so its strongly advised not to pass the verb via the URL.
The "best" way to version the API would be using HTTP headers on a per-request basis; this lets clients upgrade/downgrade specific requests instead of every single one. Of course, that granularity of versioning needs to be baked in at the start and could severely complicate the server-side code. Most people just use the URL used the access the servers. A longer explanation is in a blog post by Peter Williams, "Versioning Rest Web Services"
There is no best return data type; it depends on your app. JSON might be easier for Ajax websites, whereas XML might be easier for complicated structures you want to query with Xpath. Protocol Buffers are a third option. Its also debated whether its better to put the return protocol is best specified in the URL or in the HTTP headers.
For the most part, headers will have the largest affect on caching, since proxies are suppose to respect them when told, as are user agents (obviously UA's behave differently, though). Caching based on URL alone is very dependent on the layers. Some user agents don't cache anything with a query string (Safari, iirc), and proxies are free to cache or not cache as they feel appropriate.