Updating the Data Sources docs #6847
Conversation
rkoron007
added
the
📝 documentation
✅ Deploy Preview for apollo-server-docs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. Latest deployment of this branch, based on commit db9b9e4:
|
There was a problem hiding this comment.
looking pretty good. much of the challenge is that the existing doc page doesn't actually bother to explain the entire point of restdatasource (the fact that it's a two-level cache, one of which caches everything but only per request, and the other one respects HTTP response headers) at all... but sorry to not make sure you knew about Shane's stuff.
| willSendRequest(request: RequestOptions) { | ||
| request.headers.set('Authorization', this.token); | ||
| override willSendRequest(request: WillSendRequestOptions) { | ||
| request.headers['authorization'] = this.token; |
There was a problem hiding this comment.
we should probably mention somewhere that request now uses @apollo/fetcher like in #apolloutilsfetcher-replaces-apollo-server-env which means no Request/Headers methods
There was a problem hiding this comment.
I added a note above this code snippet:
New in Apollo Server 4: Apollo Server 4 now uses
@apollo/fetcherunder-the-hood, so you can no longer directly useRequestorHeadersmethods.
Just to double-check, does this capture the point you are making above?
There was a problem hiding this comment.
I guess, though it's more like we've actually changed the API folks write their this.post etc with. Compare the TS declarations:
https://www.runpkg.com/?apollo-datasource-rest@3.7.0/dist/RESTDataSource.d.ts
https://www.runpkg.com/?@apollo/datasource-rest@4.2.0/dist/RESTDataSource.d.ts
Like, the old API each of these take three args (path, body, other options) whereas in the new API it's two args (path, request where the body comes as a body option).
Additionally for hooks like willSendRequest, the object you have access to doesn't have Request/Header methods. But the bigger bit I guess is that the API changed! I think you have to adjust for body in the POST and PUT examples like you already did for patch.
There was a problem hiding this comment.
- I wasn't aware the args had for the HTTP convenience methods; thank you! So I'll remove this paragraph because it no longer applies:
For all methods, the third parameter is an
initobject that enables you to provide additional options (such as headers and referrers) to thefetchAPI that's used to send the request. For details, see MDN's fetch docs.
- I'm going to add this note to the "Intercepting Fetches" section to let folks know they can't access Request/Header methods directly:
New in Apollo Server 4: Apollo Server 4 now uses
@apollo/fetcherunder-the-hood for fetching, so hooks likewillSendRequestno longer have direct access toRequestorHeadersmethods.
- Great catch on that
POSTexample, thanks!
There was a problem hiding this comment.
For posterity, the package name is @apollo/utils.fetcher. (maybe you figured this out further down, I see this PR landed and I don't see any references to @apollo/fetcher 😄)
There was a problem hiding this comment.
That did get updated, thanks for calling this out, though!
docs/source/data/fetching-rest.mdx
Outdated
|
|
||
| The **second parameter** depends on the HTTP method: | ||
|
|
||
| - For HTTP methods with a request body (`post`, `put`, `patch`), the second parameter is an _object_ that contains the `method` `cacheOptions`, and request `body` (e.g., `{ body: { id: movie.id } }`). |
There was a problem hiding this comment.
it actually can contain a lot of stuff like headers too? also missing comma after method
There was a problem hiding this comment.
Okay, you were so right—my bad for not rechecking the args! I replaced this whole section with:
Method parameters
For all HTTP convenience methods, the first parameter is the relative path of the endpoint you're sending the request to (e.g.,
movies). The second parameter is an object where you can set a request'sheaders,params,cacheOptions, andbody:
class MoviesAPI extends RESTDataSource {
override baseURL = 'https://movies-api.example.com/';
// an example making an HTTP POST request
async postMovie(movie) {
return this.post(
`movies`, // path
{ body: movie }, // request body
);
}
}
docs/source/data/fetching-rest.mdx
Outdated
| The **second parameter** depends on the HTTP method: | ||
|
|
||
| - For HTTP methods with a request body (`post`, `put`, `patch`), the second parameter is an _object_ that contains the `method` `cacheOptions`, and request `body` (e.g., `{ body: { id: movie.id } }`). | ||
| - For HTTP methods _without_ a request body, the second parameter is an object with keys and values corresponding to the request's query parameters. |
There was a problem hiding this comment.
Is that actually true? I think it's a similar object which can have headers and such, and params go on params?
There was a problem hiding this comment.
(this is also addressed above)
Co-authored-by: David Glasser <glasser@apollographql.com>
Splitting out "Fetching from REST" from a more general article covering data sources.