I'm developing a REST API using Zend Framework 1.12.3. It would be useful having a param to be able to return additional information to be returned (other collections/resources or parent/child resources).
E.g. http://api.example.com/project/:id?include=Company,Company.users
where Company, Company.users represent the company to which the project is assigned to and the users of that company, and therefore these two collections are included in the response that otherwise wouldn't have been included.
I've read briefly about this (Limiting which fields are returned by the API here http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#limiting-fields), but I would like to know more.
Are there any guidelines for best practices regarding this issue? Do you have any example regrading this?
Have you ever faced a similar issue (including fields, filtering fields, etc), and how did you solve it?
Some examples of syntax used for field expansion/field selection in the wild:
Facebook's field expansion. I quite like the syntax here that allows pagination of sub resources.
LinkedIn's field selectors
We wanted to provide similar functionality on our APIs, and have gone with similar syntax to the Facebook field expansion. Unfortunately there is not much in the way of of libraries to help with this, so we have been rolling our own implementation. (There is yoga for Java, and shona for scala is in early stages, but neither of those help you with PHP).
Related
I'm trying to figure out what the latest best practice is when it comes to REST APIs and finding an elegant way to "tell" the client what the response will look like. I'm no web expert. But I just recently joined a new team and I've noticed that in the client code, they have hardcoded URI to APIs... and anytime the schema of the return data changes, they have to patch their client code.
Trying to find a way to make things more dynamic by:
introducing patterns to "discover" API servers.
looking into HATEOAS.
More than anything else though, what I'm trying improve is having to change the client code each time the logic on the server changes as far as the body of a GET response.
I've been reading this:
https://www.programmableweb.com/news/rest-api-design-put-type-content-type/2011/11/18
And in particular, the following comments stood out to me: (under the WRML heading)
this media type communicates, directly to clients, distinct and
complementary bits of information regarding the content of a message.
The Web Resource Modeling Language (WRML, www.wrml.org) provides this
"pluggable" media type to give rich web applications direct access to
structural information and format serialization code. The media type's
self-descriptive and pluggable design reduces the need for information
to be communicated out-of-band and then hard-coded by client
developers
Questions
is WRML still a thing? this book that i'm reading is from 2011... and I'm assuming a lot has changed since then.
Can I cheaply build my own inhouse solution where we use the Content-Type or some other header to provide the clients with schema information?
can you point me to an example / sample code where someone is using custom values in Content-Type or other Headers to accomplish something similar?
Or if you have any other suggestions I'm all ears.
Thank you.
I don't know much about WRML, but I would look into:
HATEOAS formats like HAL/HAL Forms and Siren, which are self-describing.
JSON-Schema to describe responses and requests (and yes they can be linked from HATEOAS responses).
If you don't want to go the hypermedia route, OpenAPI and RAML
I've been developing Ketting for the last 5 years and HATEOAS has been nothing short of magic lately as all the tools have been falling into place.
I am currently working on a Hapi-FHIR project.
There I want to implement a collection of Questionnar Responses by Patient. The collection gives back all QuestionnaireResponses of a Patient with a given PatientId.
This works without problems but I also want to adhere to the REST Resource Naming Conventions.
So the search URL for my Collection shoud look something like
https://example.com/patient/{id}/questionnaireresponses.
Right now my search URL looks like this:
https://example.com/QuestionnaireResponse?patient={id}
I already tried to set my own search Url with #Path("/patient/{id}/questionnaireresponses") but HAPI-FHIR seems to ignore this.
I searched the HAPI-FHIR documentation already but I did not find anything related.
My question is where does the naming of the search urls happen in HAPI-FHIR and how can I change the name of a search url?
While I also find the FHIR naming and syntax choices a bit annoying, they're an integral part of the FHIR specification, not specific to Hapi. If you change them, your server won't be usable by a client that is expecting the standardized FHIR API. Which kind of defeats the point of using FHIR, no?
It might well be trivial to change the resource name in a Hapi server request (Patient to patient or patients), but since it doesn't really make that much sense, it might not be. So technically you might be forced to prehandle requests to support even that part of your syntax.
For the kind of hierarchical interrogation that you want, (patient/{id}/questionnaireresponses), things are more complicated even pure semantically, because there might be more than one relationship between two resource types. Even for your example, would patient/{id}/questionnaireresponses return just the responses where the patient is the subject, or also those where he is only the author? And how would you retrieve just those he has authored? FHIR is designed to be as explicit as possible to avoid different interpretations that can lead to wrong information being sent.
HapiFhir offers a mechanism for grouping two resources together.
Using compartments solved my problem.
I'm writing an AngularJS application that's communicating with an API, and right now that API is following the REST architecture.
I know the basics of REST, but I've still not understood if REST only covers the CRUD operations? For example, if I'm building a community website and I want to make it possible for people to add each other as friends, is this covered by REST in any way? What about search queries? If not, is there any other architecture that's recommended to follow, or should I roll my own?
Also, should I even be using REST for a community website? There are a lot of cases where it seems like it's not the optimal design, but when I google around I only get results saying that REST is the best practice. For example PUT /api/user/:id wouldn't be very useful, since the only user you're able to update (unless you're an admin) is yourself.
It all depends, REST is just an architectural style and (in many forms unfortunately) is used all over the world. I also follow REST rules in all type of applications but try to stay at the second level of Richardson's Maturity Model. Why? Since I consider HAL, HATEOAS and all the API discoverability as an unnecessary buzz - unfortunately documentation is still very important.
What you need to consider while designing an API is if it's going to public or not. If it's not, you can probably whatever you want/need (of course this is not good idea). If it is going to be public the consistency starts to play a great role - API needs to be designed in such a way that it will be both intuitive and easy to use. E.g. this is not good idea to introduce new endpoint every time you need a new operation - thus following CRUD REST rules seems to be reasonable option. When it comes to to going beyond CRUD - yes, I've created APIs with verbs in endpoints - but it was almost always the last resort and to be honest I don't feel guilty.
I think the question is a bit too broad, but I'll try to answer.
REST only covers the CRUD operations?
No, it covers other operations as well. You have to transform your operation into a HTTP method and a resource. The resource can have identifiers: URIs. An URI with a HTTP method compose a hyperlink. This hyperlink can be followed by the client. You can attach the operation name, etc... to the hyperlink as meta-data, so it can be used by the client to recognize the operation. At least that's how it should work.
What about search queries?
General queries are not supported currently, because there is no standard RDF vocab which could be used to describe a general query. There are non-standard workaround, you can use them or for example a SPARQL endpoint. More fixed queries can be used with URI templates.
Also, should I even be using REST for a community website?
As far as I know facebook uses it for 3rd party clients, so you can develop a facebook application using their REST API. Another advantage that it scales better than SOAP. If you don't need these features currently, then you can use something else you are more familiar with.
I'm completely new to REST. I helped to implement something that was called REST at work but it breaks so many of the rules that it's hard to qualify it as REST. I want to follow the HATEOAS guideline and the remaining question I have is regarding documentation of media types and their specification. Namely when one media type is really an extension of another.
For example, I've decided on 'application/hal+json' for the base media type. Everything that a user would receive is going to be a HAL blob with some added fields. I don't want to call my media types just 'application/hal+json', it seems to me more information should be available than that, but I want it to be clear that this is what they are in addition to the extra fields that are my data. Furthermore my system is going to end up having some of these fields inherited and such in both the request (which won't be HAL blobs) and response formats. A generic "User" type might have just a user id and name for example while an extension like "Student" or "Teacher" will have different additional fields.
Does it make sense to represent this extension somewhere in the media type itself? Do people generally document the relationship in their HATEOAS documentation links? If so, what's the general trend here? I want my API to be easy to use and thus figure it should follow norms that are available.
Couple of things i'd like to point out about your move to a true RESTful architecture.
First, RESTful APIs must perform content negotiation. To say your base type is hal+json is seems strange. It sounds like you want to have types like parent+hal+json or maybe hal+json;type=parent. This would mean your client would have to understand these types specifically...and this would be not very RESTful because it's just a local implementation. This is fine in the real world..you can do this...almost everyone does stuff like this.
To be true RESTful api you'd have to offer similar support for other content types...that could get messy.
Now specifically to HAL, there's two things available to you so that your client can "discover" what data types they are getting back. One is CURIEs and the other is Profiles https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06#section-5.6 I think Profiles is more what you're after here as it allows you to document conventions and constraints for the resource that will be retrieved.
But don't count out CURIE's either. There's lots of defined semantics out there already. Your model might fit one of http://schema.org sets and then you can just use their link relationships and the client should know what's going on.
If you really want a lot of control on the semantics of your resources...you may want to look at http://json-ld.org/ with it's #context concept would be a good reference.
In my opinion this is an area where the examples are very thin, especially for HAL. I've yet to seen a client smart enough to parse and care about semantics at run time. What i think is important is when someone is building the client that info is available they can figure out that a Student is a Person. One day the thing building the clients will be client generator code and it'll use that info to build a nice client side object model for you.
TL;DR if you stick with HAL use CURIEs and Profiles to get what you want.
This question is an extremely open ended discussion and it really depends on how different engineers interpret REST standards and best practices. Nonetheless, As a fellow software engineer with enough experience with REST services development (and faced the same questions professionally as you did), I would add my inputs here.
REST service development rules are heavily dependent on the url definitions. It's very important that you expose your apis in such a way that your clients can understand exactly what's happening per api just by looking at the url definition.
With that being said, different clients (and for that matter different engineers) view the best practices differently. For example, if you are trying to search a User by email, there are atleast two approaches
1) GET /users/emails/{email} // A client can interpret this as
"getting a user by email"
2) GET /users?email={email} // A client can interpret this as
"searching a user by email" because of query param
3) GET /users/email={email} // This can be interpreted just as # 1
It depends on the developer how they want to expose this api and how they document it for the clients. All the approaches are correct in different perspectives.
Now going specific to your questions. Here's what my approach would look like in terms of "User", "Student" and "Teacher".
I look at each of these 3 as separate resources? Why? because they are separate types even though 2 of them are extended from the 3rd one. Now how would my apis look like for these?
For Student:
1) Retrieving a list of students : GET /students
2) Retrieving a Student with id: GET /students/{id}
3) Creating a Student : POST /students
4) Updating a student : PUT /students/{id}
5) Delete a student: DELETE /students/{id}
6) Search a student: GET
/students?{whateverQueryParamsYouWantForSearch}
The same will be applied for Teacher as well.
Now here's for User.
1) GET /users : Retrieving list of all the users (Students and
Teachers)
2) GET /users?type={type} : Here's the kicker. You can specify the
type to be student OR teacher and you will return the data of specific
type (properly documented ofcourse)
3) POST /users?type={type} : Create a specific TYPE of user
(student or teacher)
.. And so on.
The main difference is .. the apis with root url /users can be used for BOTH types of users (Provided the type is always specified and documented to the clients). While the Student and Teacher apis are specific to those types.
My money has always been on specific types while generic types for searching (meaning for searching both types of users .. use /users?params). It's the most easy way for the clients to understand what's going on. Even documenting them is much easier.
Finally talking about HATEOAS. Yes, it's a part of the standards and the best practice is to ALWAYS provide a url/link to the resource you are returning or if your return object is complex and contains other resources which might contain resources who might themselves be exposed through apis. For example,
/users?type=student&email=abc#abc.com
will return all users with that email and it's better to follow HATEOAS here and provide a url to each returned user such that the url looks like : /students/{id}. This is how we have normally handled HATEOAS
That is all I have to add. As I said earlier, its a very open ended discussion. Each engineer interprets the standards differently and there is no ONE WAY to handle all usecases. There are some base rules and the clients and other developers will applaud you if you follow them :)
How do you document a REST API? Not just the documentation of what the resources are, but really what is the data that gets sent in the request and what the data is that gets sent back in the response. It is not useful enough to know that something expects XML to be sent and returns XML; or JASN; or whatever. How do you document the data that gets sent in the request and the data sent back in the response?
Best I could find so far is the Enunciate tool where you can document your REST API and the data elements. Is Enunciate the right type of tool for this and am I missing out on any other tools that offer this that I should look at?
Consumers of my REST API can be in any language python, Java, .NET, etc
The approach that I've decided on for my project is Enunciate. Seems to be the de facto standard for REST API documentation.
I've experience using Enunciate which is great but I don't really like the clients that you can generate with it.
On the other hand, I've been using swagger on my last projects and it seems to fit my needs, it's really cool you should give a try!
UPDATE 03/08/2016: Looks like you can use Enunciate to build swagger docs.
See this.
I may be wrong, but it seems like you want something similar to a WSDL and XML Schema to document your API. I suggest reading Joe Gregorio's post on Do we need WADL? It has a good discussion on why not to use this approach for a REST API. If you don't want to read the entire article, the basic idea is that API-like documentation (i.e. WADL) will never be sufficient and will lead to brittle interfaces. Another good article is Does REST need a description language? It has a lot of good links to this type of discussion.
While his post gives you advice on what not to do, it doesn't really answer the question on what you should do. The big thing about REST is the idea of a uniform interface. In other words, GET, PUT, POST, and DELETE should do exactly what you think they should do. GET retrieves a representation of the resource, PUT updates, POST creates, and DELETE deletes.
The big question is then about describing your data and what it means. You can always go the route of defining an XML Schema or something similar and generate documentation from the schema. Personally, I don't find machine generated documentation all that useful.
In my humble opinion, the best data formats have extensive, human readable documentation with examples. This is the only way I know how to properly describe semantics. I like the use of Sphinx to generate this type of documentation.
I am not sure if you are asking for a tool to assist you in this, or if you're asking what the best practice is (or both).
As far as best practices, the same things apply to REST documentation as other software documentation - provide a good landing page with breadth (ie, a list of your resources logically organized with a blurb about what they do and their URI) with drill-down pages that explain in depth what each one does, with examples. Twitter's REST API is very well documented and it should be a good model.
Twitter API main page
Sample drilldown of one resource
I really love that drilldown page. It lists all of the parameters you need, with a description of each one. It has a sidebar that lists the supported types. It has links to related pages and other pages with the same tag. It has a sample request and response.