Skip to content

Latest commit

 

History

History
69 lines (37 loc) · 5.38 KB

Jayme 4.0 Migration Guide.md

File metadata and controls

69 lines (37 loc) · 5.38 KB
Raw

Jayme 4.0 Migration Guide

Jayme 4.0 is the latest major release of Jayme. As a major release, following Semantic Versioning conventions, 4.0 introduces several API-breaking changes that one should be aware of.

This guide is provided in order to ease the transition of existing applications using Jayme 3.x to the latest APIs, as well as explain the design and structure of new and changed functionality.

Based in our experiences by using Jayme in production projects, we've decided to focus Jayme 4.0 on an enhanced CRUD API design, that is better organized as of this version, and provides more functionality.

Better organized CRUD API

The main change that you need to be aware of is that your repositories will no longer conform to a CRUDRepository protocol. Instead, they can conform to Creatable, Readable, Updatable and Deletable protocols, depending on what each repository needs.

By organizing the CRUD API this way, your code will follow the YAGNI principle better than before. For instance: If you have a repository whose entities only need to be read, but not created, updated or deleted, then you shouldn't need to write a dictionaryValue method for that entity type at all. You were forced to do so when conforming to CRUDRepository, but now, by only conforming to the Readable protocol, you don't have to.

This new organization has been discussed in the issue #84. Check it out for further reference.

More CRUD functionality

The other breakthrough is that now repositories can be aimed to perform operations in two ways: single-entity or multiple-entity.

Typical examples of single-entity endpoints are /me, /profile or /device, whereas typical examples of multiple-entity endpoints are /users, /posts, /feed_items or /comments.

Sometimes your repository needs to perform operations that always apply to a single entity. Under this scenario, your repository would not, for instance, delete an entity by id, instead, you would prefer to use a generic delete() method to delete the only entity that lives in the repository, and not the delete(id:) method.

Below is a table exposing all the methods that are available in the Creatable, Readable, Updatable and Deletable protocols, categorizing them by interest: �single vs. multiple entity repository.

Single-Entity Repository
(e.g. /profile)		Multiple-Entity Repository
(e.g. /users)
Creatable.create(e)
POST /profile → ⚪ 		.create(e)
POST /users → ⚪

.create([e1, e2, ...])
POST /users → [⚪ ,⚪ , ...]
Readable.read()
GET /profile → ⚪ 		.read(id: x)
GET /users/x →⚪

.readAll()
GET /users → [⚪ ,⚪ , ...]
Updatable.update(e)
PUT /profile → ⚪		.update(e, id: x)
PUT /users/x → ⚪

.update([e1, e2, ...])
PATCH /users → [⚪ ,⚪ , ...]
Deletable.delete()
DELETE /profile		.delete(id: x)
DELETE /users/x

This new organization has been discussed in the issue #87. Check it out for further reference.

Automatically Suggested Changes

There are some compiler migration mechanisms that have been implemented in Jayme 4.0 via a Compatibility.swift file.

For these changes you only have to follow the compiler suggestions and they should be applied automatically.

For instance, findAll() has been renamed to readAll(): The compiler will automatically suggest the replacement of findAll() to readAll().

Manual Changes

However, there are some other changes that would have required overwhelming (if ever possible) mechanisms to be implemented in order to keep automatic suggestions from the compiler. In consequence, we decided not to implement them.

⚠️ Therefore, it's up to you to perform these changes manually.

  • CRUDRepository no longer exists. The compiler will suggest you to use the Creatable, Readable, Updatable and Deletable protocols instead, but it's up to you to write which ones each of your repository needs to conform to.
  • Watch out the update(_) method. In Jayme 3.x, this method appends the entity's id to the URL path. In Jayme 4.x, this method does not append the id, there is the update(_, id:) method for doing so. Therefore, anywhere you were calling update(entity), you have to change it by update(entity, id: entity.id). You have to do it manually, because update(entity) still compiles, but has a different behavior as of Jayme 4.0.
  • PagedRepository no longer exists. The compiler will suggest you to use the Readable protocol instead. However, you have to manually change any call to the findByPage(pageNumber:) method, which now is read(pageNumber:pageSize:).
  • Dictionaries are now represented as [AnyHashable: Any] instead of [String: Any]. You have to manually change these appearances in your DictionaryInitializable and DictionaryRepresentable methods of your entities.

For further documentation regarding changes, check out the Change Log.