doc: Please describe the difference between update and patch

[lorenzleutgeb]

Hello!

There are two methods update and patch and they look very similar. Could you please describe what is the difference between them and maybe add this to the documentation. Thank you!

[tomers]

Indeed both methods are similar. Both eventually call PATCH request, but they have subtle differences, as update is called with modelName, while patch is called from a URL builder.

update usage:
jsonApi.update('foo', {title: 'foo'}, {include: 'something'})

patch usage:
jsonApi.one('foo', 1).patch({title: 'bar'})

Code:

  update (modelName, payload, params = {}, meta = {}) {
    let req = {
      method: 'PATCH',
      url: this.urlFor({model: modelName, id: payload.id}),
      model: modelName,
      data: payload,
      params: params,
      meta: meta
    }
    return this.runMiddleware(req)
  }

  patch (payload, params = {}, meta = {}) {
    let lastRequest = _last(this.builderStack)

    let req = {
      method: 'PATCH',
      url: this.urlFor(),
      model: _get(lastRequest, 'model'),
      data: payload,
      params,
      meta
    }

    if (this.resetBuilderOnCall) {
      this.resetBuilder()
    }

    return this.runMiddleware(req)
  }

Test code:

    it('should make basic update call', (done) => {
      let inspectorMiddleware = {
        name: 'inspector-middleware',
        req: (payload) => {
          expect(payload.req.method).to.be.eql('PATCH')
          expect(payload.req.url).to.be.eql('http://myapi.com/foos')
          expect(payload.req.data).to.be.eql({title: 'foo'})
          expect(payload.req.params).to.be.eql({include: 'something'})
          return {}
        }
      }

      jsonApi.middleware = [inspectorMiddleware]

      jsonApi.define('foo', {
        title: ''
      })

      jsonApi.update('foo', {title: 'foo'}, {include: 'something'})
        .then(() => done()).catch(() => done())
    })

it('should allow builders to be called with patch', (done) => {
      let inspectorMiddleware = {
        name: 'inspector-middleware',
        req: (payload) => {
          expect(payload.req.method).to.be.eql('PATCH')
          expect(payload.req.url).to.be.eql('http://myapi.com/foos/1')
          expect(payload.req.data).to.be.eql({title: 'bar'})
          return {}
        }
      }

      jsonApi.middleware = [inspectorMiddleware]

      jsonApi.one('foo', 1).patch({title: 'bar'}).then(() => done()).catch(() => done())
    })