I have a PostgreSQL database with various relationships between different entities/tables. E.g. teachers and students, teachers and classrooms, students and classes. In my (express) backend*, I find myself writing a lot of tedious routes to extract data - the routes make similar but slightly different SQL queries (we use sequelize), e.g.
get students based on age
get teachers based on school
get all students that learn with particular teacher(s)
get all teachers that teach particular student(s)
get all students that went to a class between certain times
get all students that went to a class between certain times and had certain teacher(s).
granted, the last 2 could be merged into one REST endpoint easily by passing null for a when no teachers constraint. Still, there are many many more permutations and that number is only growing with new entities.
To speed up development, I am wondering if (i) GraphQL would buy us anything (we have ~30 routes today) (ii) if it is even possible to setup and use GraphQL to somehow connect to my postgreSQL (and redis) database without doing a LOT of boiler plate work.
I have had a look through the Apollo docs (https://www.apollographql.com/docs/tutorial/data-source/), and looking at SQLDataSource (https://github.com/cvburgess/SQLDataSource), it seems that I still need to write/expose endpoints for every one of my scenarios - e.g. if i want to find which students have which teachers I still need to write a manual SQL query to do that and expose that as a method on a SQLDataSource object. I presume I am misunderstanding something here as I thought this was a key value proposition of GraphQL.
Thank you so much!
*we just have 1 service today but are adding another shortly
Based of you requirements, I only see three endpoints, one with few query params but nothing so complex, as example:
GET /students
GET /students?birthdate=<birthdate_year>
GET /students/<student_id>/teachers
GET /students?class_dtstart=<dtstart>&class_dtend=<dtend>
GET /students?class_dtstart=<dtstart>&class_dtend=<dtend>&teacher_id=<teacher_id>
GET /schools/<school_id>/students
GET /teachers/<teacher_id>/students
I think that you can play to few endpoints with some params to build the query that you want in a clasic rest api schema. Obviously you need to write somo code to transform que route params to your SQL query but I think it is not very complex.
Related
We are creating api on employee manage app. So there is schedule in interface, where we have to show all shifts in table, for every user per row. Farther, there is summary for every user (per row) and day (per column). Should we create one big aggregate call like:
GET /api/locations/{id}/shedule
which will return all employees, shifts, summaries etc. Or maybe should we smash that to several collections like:
GET /api/locations/{id}/shifts
GET /api/locations/{id}/events
GET /api/locations/{id}/summary
GET /api/employee/{id}/summary?date_from={date_from}&date_from={date_to}
For me, second option is more flexible and there is no reason to create new abstract resource, which is shedule. In my opinion it is clearly part of interface layer and should not affect on API design.
On the other hand the big aggregate is more optimal, becouse there will be less database calls and it's easy to cache.
How do you think? Is there any source, kind of article, which can I rely on?
There's nothing RESTful or unRESTful about either approach. The semantics of URIs is irrelevant to REST. What really matters is how the clients obtain the URIs. If they are looking up URI patterns in documentation and filling up values instead of using links, the API is not RESTful.
With that in mind, I'd say the approach that is more consistent with your business and your ecosystem of applications is the best one. Don't be afraid to create aggregate resources if you feel the need to.
I'm playing around with a spare time project, mainly to try out new stuff :)
This involves designing a REST API for a system that is multi tenant. Lets say you have an "organization" that is the "top" entity, this might have an API key assigned that is used for authenticating each request. So on each request we have an organization associated.
Now when a user of the API would like to get a list of, lets say projects, only those that belong to that organization should be returned. The actual implementation, the queries to the database, is pretty straight forward. However the approach is interesting I think.
You could implement the filtering each time you query the database, but a better approach would be a general pre-query applied to all "organization" related queries, like all queries for enities that belong to an organization. It's all about avoiding the wrong entities from being returned. You could isolate the database, but if that is not possible how would you approach it?
Right now I use NancyFX and RavenDB so input for that stack would be appreciated, but general ideas and best practices, do's and don't is very welcome.
In this case you could isolate your collections by prefixing them with the organization_id. It will duplicate maybe many collections.
Use case with mongodb: http://support.mongohq.com/use-cases/multi-tenant.html
Say I have an app for patients and doctors.
Patients should be able to access their information at `site.com/api/patients/.
Doctors should be able to access information about the patients as well, but would receive different information than the patients.
I can imagine two ways of handling this:
api/patients with logic to split between different permissions
OR
api/patients for patients AND
api/doctors/patients for doctors getting information about patients
This seems relatively fine, but then I started thinking about what happens when both a doctor AND a patient can add tasks for a patient.
api/patients/tasks/ for a patient to add a task BUT
api/doctors/patients/tasks Which gets pretty bad as far as nesting goes (Where I believe it might be better to limit the depth of my routes)
Is it simply better to have api/patients and check for whether the user is a doctor or a patient or to nest resources? What is the consensus on best practice (if there is one)?
It would be nice to have API endpoints like:
api/tasks/
api/patients
api/doctors/
which keeps things simple, and then control permissions/authentication with a token or query string.
Definitely don't do api/doctors/patients, etc.
Should this be two different APIs, one for Doctors and one for Patients? It depends on how much overlap of functionality there is.
In any event, you should already be tracking authentication/authorization information for your users. Otherwise you'll have doctors modifying patients who don't go to them. Use the auth info to determine what values/options are supported for the caller.
I assume you're handling the case where I copy Dr. Bob's token/query string and send my own requests?
I've been reading a lot and I understand that a REST API maps resources with HTTP verbs. That's very easy of understand when, for example, a tutorial show an example like Employee.
A PUT will be a new record (if it doesn't exist) or an update; a GET will extract a list with all employees, and a GET api.example.com/employee/12 will extract the record for the Employee with ID = 12.
But, for example, how I could map a more useful queries like "get me all the employees with a salary under 50.000, with less that 2 years at the company and with the marital status as single"?
In other words, how I could parametrize the query? Is it correct to add parameters like api.example.com/Employee?salary<50000&years<2&marital-status=single" ?
The theory:
If you add parameters to your query, they are just part of the URL. The form of the URL does not tell you anything about whether your API is RESTful. Your API with query strings is restful if it obeys the constraints described here: http://en.wikipedia.org/wiki/Representational_state_transfer and (optionally) follows the guiding principles
So as long as your query parameters don't do anything crazy like randomly change the state of some of the resources, then your API is still RESTful
The practice:
Any sensible REST API will need query parameters for the 'index' route. In practice, LinkedIn's REST API has query parameters that just select fields from someone's profile. In this case, the URLs looks completely different from yours, but still obey the principles of REST.
Your situation:
Your query strings can't contain inequalitites, only key+value pairs. You need to express it more like ?max-salary=50000&max-years=2&marital-status=single". You might also name your 'index' route differently: api.example.com/employees (plural)
I'm currently designing an API and I came a cross a little problem:
How should a URL of a RESTful API look like when you should be able to identify an item by either an ID or a slug?
I could think of three options:
GET /items/<id>
GET /items/<slug>
This requires that the slug and the ID are distinguishable, which is not necessarily given in this case. I can't think of a clean solution for this problem, except you do something like this:
GET /items/id/<id>
GET /items/slug/<slug>
This would work fine, however this is not the only place I want to identify items by either a slug or an ID and it would soon get very ugly when one wants to implement the same approach for the other actions. It's just not very extendable, which leads us to this approach:
GET /items?id=<id>
GET /items?slug=<slug>
This seems to be a good solution, but I don't know if it is what one would expect and thus it could lead to frustrating errors due to incorrect use. Also, it's not so easy - or let's say clean - to implement the routing for this one. However, it would be easily extendable and would look very similar to the method for getting multiple items:
GET /items?ids=<id:1>,<id:2>,<id:3>
GET /items?slugs=<slug:1>,<slug:2>,<slug:3>
But this has also a downside: What if someone wants to identify some of the items he want to fetch with IDs, but the others with a slug? Mixing these identifiers wouldn't be easy to achieve with this.
What is the best and most widely-accepted solution for these problems?
In general, what matters while designing such an API?
Of the three I prefer the third option, it's not uncommon to see that syntax; e.g. parts of Twitter's API allow that syntax:
https://dev.twitter.com/rest/reference/get/statuses/show/id
A fourth option is a hybrid approach, where you pick one (say, ID) as the typical access method for single items, but also allow queries based on the slug. E.g.:
GET /items/<id>
GET /items?slug=<slug>
GET /items?id=<id>
Your routing will obvious map /items/id to /items?id=
Extensible to multiple ids/slugs, but still meets the REST paradigm of matching URIs to the underlying data model.