You’ve asked two questions here and I think things will make more sense with a deeper dive into API architecture. The first thing I will say is than an API should ALWAYS have an independent ViewModel as the request/response data objects. I’ll address that in more in question 2.
ViewModel: A data model passed between an external entity and the presentation layer of a web application. APIs are a web application with a presentation layer, therefore, they have ViewModels though we call them several different things (contracts, requests, responses, etc). (Human (entity) -> web page (presentation layer)) (App (entity) -> Api Controller (presentation layer))
You can think of ViewModels more as a role than a naming convention in regards to APIs; you might be use to seeing these data vehicles called by another name. As long as they're there, all is well.
Does it make sense to pass back from the API only the fields our view will use? No – this is assigning the wrong responsibility to the API. API’s expose units of business logic therefore what we need to return is the business process data, not the data needed for a specific page’s view model. It’s the job of your site’s adapter to map the business model to your page’s ViewModel. Now, it might happen to be that your business model and view model are identical, but that’s coincidence, not design. The API should have no knowledge of what the web page needs to render, that’s the website’s responsibility. If a process needs to return more data than the page will use, so be it.
Should an API use ViewModels? YES! Always! A well-designed API will have at least 3 layers: Presentation (Api layer, UI layer), Core (sometimes called application, business or/and domain), and Infrastructure (sometimes called data or service layer) The Presentation layer will have ViewModels, the Core layer will have your business models, and the Infrastructure layer will have DTOs and external service ViewModels/Contracts. You will have adapters (aka mappers) that transform these objects into one another. There are two big reasons for this (among any others); most important is security and mutability.
ViewModels & Security: As a security principal you should never return your business object nor your data object through a presentation layer. Most often we have data in those objects for operation that doesn’t need to be exposed. Rule of thumb is to return as little data as possible. Additionally, our business layer often needs access to raw data but the presentation layer should only expose scrubbed data. Take a credit card number for example. The business layer operates on the full number, but the presentation layer returns a number xxxxx4856 masked. If your consuming apps never needs the full #, never pass it in the first place as a defensive design.
ViewModels & Mutability: Another reason to build your API with the extra models/adapters is mutability. We want to build our API with as much Separation of Concern as possible. Here is an example. Let’s say we return card data. We learn to we’re not allowed by law to display, store, or operate on the card number and the CVV together so we decide to remove CVV from being returned from the API. Uh oh – we were returning our business model as the response to the call. Now we must change a business model which affects the Core layer logic and the Presentation layer logic – gross. If we use a ViewModel to begin with, we simply do not return the CVV in the ViewModel, the Core remains unchanged and happy.
There are three key things to think about when developing an API, even one used as a lean standalone operation layer for a website (doesn’t model business rules).
- Separation of Concerns
- Ports and Adapter Pattern
- Formal API Architecture – I personally like the Clean Architecture for improved testability and mutability. I highly recommend you learn a strong API Architecture as it’ll resolve a lot of questions for you as you start to understand areas of responsibility in your API and why. Again, I’m a big fan of Clean Architecture which is also highly recommended by Microsoft. (Presentation/Core/Infrastructure naming convention of the layers I referenced is a Clean Architecture convention.) Feel free to explore others; Hexagonal, Onion, N-Tier, etc etc. I’ll leave you to Google for that.
