I've done some research into the subject of response serialization for NestJS/GraphQL. There's some helpful information to be found here, but the documentation seems to be completely focused on a code first approach. My project happens to be taking schema first approach, and from what I've read across a few sources, the option available for a schema-first project would be to implement interceptors for the resolvers, and carry out the serialization there.
Before I run off and start writing these interceptors, my question is this; is there any better options provided by nestjs to implement serialization for a schema first approach?
If it's just transformation of values then an interceptor is a great tool for that. Everything shown for "code-first" should work for "schema-first" in terms of high level ideas of the framework (interceptors, pipes, filters, etc). In fact, once the server is running, there shouldn't be a distinguishable difference between the two approaches, and how they operate. The big thing you'd need to be concerned with is that you won't be easily able to take advantage of class-transformer and class-validator because the original class definitions are created via the gql-codegen, but you can still extend those types and add on the decorators necessary if you choose.
I'm building an API and I have modeled the entities I need inside it. By example
User
Name
Email
City
Company
Name
Website
I'm using Blueprint to specify the API itself and I need to create endpoints for CRUD operations in pretty much every entity. The task seems very redundant to me - besides some tuning that is needed in some specific entities, most of the basic skeleton looks like the same.
I wonder if there is any tool that allows me to write down my entities, its fields and types and generates this basic skeleton.
I was about to start creating one and then I stopped to look around if there already is one but I did not find anything yet...
API Blueprint contains a tool to write, use, reuse, compose, inherit your data structures, and it's MSON.
Basically it's a way to describe your data structures within an API Blueprint. We do also provide an html renderer for that, and it's the Attributes Kit. Try also to have a look to its Playground.
You can find an useful tutorial on official website, as well more information.
Hopefully it should be enough to get started.
Cheers,
V.
I'm trying to make an architectural decision and I'm worried that I'm missing something big about URL routing / mapping when it comes to designing a basic REST API / framework.
Creating routing classes and such that is typically seen in REST API frameworks, that require one to manually map a URL to a class, and a class method (action), kind of seems like a failure to encapsulate the problem. When this can all be determed by parsing the URL dynamically and having an automatic router or front page controller.
GET https://api.example.com/companies/
Collection resource that gets a list of all companies.
GET https://api.example.com/companies/1
Fetches a single company by ID.
Which all seems to follow the template:https://api.example.com/<controller>/<parameter>/
Benefit 1: URL Decoupling and Abstraction
I assume one of the on paper benefits of having a typical routing class, is that you can decouple or abstract a URL from a resource / physical class. So you could have arbitrary URL's like GET https://api.example.com/poo/ instead of GET https://api.example.com/companies/ that fetches all the companies if you felt like it.
But in almost every example and use-case I've seen, the desire is to have a URL that matches the desired controller, action and parameters, 1 : 1.
Another possible benefit, is that collection resources within a resource, or nested resources, might be easier to achieve with URL mapping and typical routers. For example:
GET https://api.example.com/companies/1/users/
OR
GET https://api.example.com/companies/1/users/1/
Could be quite challenging to come up with a paradigm that can dynamically parse this to know what controller to call in order to get the data, what parameters to use, and where to use them. But I think I have come up with a standard way that could make this work dynamically.
Whereas manually mapping this would be easy.
I could just re-route GET https://api.example.com/companies/1/users/ to the users controller instead of the companies controller, bypassing it, and just set the parameter "1" to be the company id for the WHERE clause.
Benefit 1.1: No Ties to Physical Paths
An addendum to benefit 1, would be that a developer could completely change the URL scheme and folder structure, without affecting the API, because everything is mapped abstractly. If I choose to move files, folders, classes, or rename them, it should just be a matter of changing the mapping / routing.
But still don't really get this benefit either, because even if you had to move your entire API to another location, a trivial change in .htaccess with fix this immediately.
So this:
GET https://api.example.com/companies/
TO
GET https://api.example.com/v1/companies/
Would not impact code, even in the slightest. Even with a dynamic router.
Benefit 2: Control Over What Functionality is Exposed
Another benefit I imagine a typical router class gives you, over a dynamic router that just interprets and parses the URL, is control over exactly what functionality you want to expose to the API consumer. If you just do everything dynamically, you're kind of dropping your pants, automatically giving your consumer access to the entire system.
I see this as a possible benefit for the dynamic router, as you wouldn't then have to manually define and map all your routes to resources. It's all there, automatically. To solve the exposure problem, I would probably do the opposite by defining a blacklist of what functionality the API consumer shouldn't be allowed to use. I might be more time effective, defining a blacklist, then defining each and every usable resource with mapping. Then again, it's riskier too I suppose. You could even do a whitelist... which is similar to a typical router, but you wouldn't need any extended logic at all. It's just a list of URL's that the system would check, before passing the URL to the dynamic router. Or it could just be a private property of the dynamic router class.
Benefit 3: When HTTP Methods Don't Quite Fit the Bill
One case where I see a typical routers shining, is where you need to execute an action, that conflicts with an existing resource. Let me explain.
Say you want to authenticate a user, by running the login function within your user class. But now, you can't execute POST https://api.example.com/users/ with credentials, because that is reserved for adding a new user. Instead, you need to somehow run the login method in your user class. You don't want to use POST https://api.example.com/users/login/ either, because then you're using verbs other than the HTTP methods. However, with a typical router, you can just map this directly, as said before. Easy.
url => "https://api.example.com/tenant/"
Controller => "users"
Action => "login"
Params => "api_key, api_secret"
But, once again, I see an plausible alternative. I could just create another controller, called login or tenant, that instantiates my user controller, and runs the login function. So a consumer could just POST https://api.example.com/tenant/, with credentials, and blam. Authentication.
Although, to get this alternative to work, I would have to physically create another controller, when with a URL mapper, I wouldn't need to. But this seperation of concerns, functionality and resources, is quite nice too. But, maybe that's the main trade off, would you rather just define a URL route, or have to create new classes for each nuance you encounter?
What am I not seeing, or understanding? Am I missing a core concept here and just ignorant? Are there more benefits to having typical URL mapping and routing classes and functionality, that I'm just not aware of, or have I pretty much got this?
A lot of the benefits to routing you describe are correct, and some of what you say about physical mappings is also true. I'd like to throw in some experience / practical information that colored my opinion on routers over the last few years.
first of all, the dynamic parsing of url works well (most of the time) when you architect your application according to the MVC design pattern. For example, I once built a very large application using Kohana, which is a hierarchical MVC framework, which allows you to extend controllers and models for the sake of making nested urls. In general, this makes a lot of sense. But there were a lot of times where it simply didn't make much sense to go build a whole class and model system around the need for one-off URLs to make the application more functional. But there are also times where MVC is not the design pattern you're using, and thus it is not the defining feature of your API, and routing is beautiful in this scenario. One could easily see this issue at work by playing with frameworks that have a lot of structural freedom, such as Slim framework or Express.js.
more often than people think, a fully functional API will have an element of RPC-ness to it in addition to the primarily RESTful endpoints available for consumption. And not only do those additional functionalities make more sense as a consumer when they're decorating existing resource method mappings. This tends to happen after you've built out most of your application and covered most of your bases, and then you realize that there are a couple little features you'd like to add in relation to a resource that isn't doesn't cleanly fit into the CREATE / READ / UPDATE / DELETE categories. you'll know it when you see it.
it really can not be understated, it is much safer to not go hacking on the actual structure of the controllers and models, adding, removing, changing, things for the sole purpose of adding an endpoint that isn't inherently following the same rules of the other controller methods (API endpoints).
another very important thing is that your API endpoints are actually more maleable than we often realize. What I mean is, you can be OK with the structure of your endpoints on monday, and then on friday,you get this task sent down from above saying you need to change all of these API calls to be of some other structure, and thats fine. but if you have a large application, this requires a very, very significant amount of file renaming, class renaming, linkages, and all sorts of very breakable code when the framework you're using has strict rules for class naming, file naming, physical file path structure and stuff like that...just imagine, changing a class name to make it work with the new structure, and now you've got to go hunt down every line of code that instantiated the old class, and change it. Furthermore, in that scenario, it could be said that the problem is that your code is tightly coupled with the url structure of your API, and that is not very maintainable should your url needs change.
Either way, you really ought to decide whats best for the particular application. but the more you use routers, the more you'll see why they're so useful.
I am looking at a rails app and at the top of every controller there is a block of code that looks something like this
expose(:var) {Model.find params[:var_id]}
I understand what is inside the block just fine but...
I cannot find any documentation on what the expose function does where it comes from or anything I have tried searching the project and using the searchable rails docs.
I would love to know what it does, can someone please tell me or point me to the docs.
This is probably referencing the decent_exposure gem. You can learn more about it here: http://railscasts.com/episodes/259-decent-exposure
Source: https://github.com/voxdolo/decent_exposure
It's a method from the Decent Exposure gem. You can check out a screencast that Ryan Bates did on it over at Railscasts. It's a really great gem. I use it in my application. It cuts down on a lot of the redundancy in the controller layer.
expose is not a part of Rails, it comes from the decent_exposure gem.
It is not an answer to the question. I just want to make the Rails world a bit better and I hope that somebody will read this.
Please think twice before using expose. You should only use it if you 100% sure you are using it the right way and it really makes the code better. Read the documentation properly!
One of projects I worked on became unmaintainable because of tons of expose in controllers which replaced not only all #instance_variables passed to views, but also a lot of business logic and the most helper methods.
When you use expose it is not clear in which controller actions and in which views it is used. Unexperienced developers combine data and logic for multiple actions and multiple views in the same expose block.
That's a nightmare.
Believe me, expose really destroys projects if not used properly.
What is NHibernate Interceptor, and what purpose does it serve in an application?
Also, in this article, I learned that using NHibernate makes a desktop application slower at startup, so to avoid this, I need to save the configuration in a file, and later load it from the saved file. How can I do that? I didn't find any examples in that tutorial.
An interceptor allows you to execute additional functionality when an entity is retrieved / deleted / updated / inserted in the DB ...
Interceptors article
Hibernate doc
other useful info
About making your app slower:
I'd suggest that you only have a look at optimizing start-up time, when it really becomes a problem.
When you build a session-factory, NHibernate will parse all the mappings, and that is an operation that is a bit expensive. But, as long as you have a limited number of entities, the performance hit isn't that big.
I have never ever had to optimize the initialization of NHibernate, because of slow startup times.
I'd suggest that you first concentrate on the core of your application -the problem you're trying to solve- and afterwards have a look on how you could improve startup performance.
(If you'll ever have to do it).
Interceptors, like the name itself says, allows you to intercept NHibernate operations (save/update/delete/load/flush/etc).
A newer, more flexible API to achieve this is the event system.
About serializing the configuration, the code is there, it's the class Effectus.Infrastructure.BootStrapper which is called at application startup.
An interceptor's dissection series written by me can be found in here
http://blog.scooletz.com/2011/02/03/nhibernate-interceptor-magic-tricks-pt-1/
hope it helps