Ash Elixir•3y ago

How to use define_interface example in docs it's not clear

Show where you found the issue I have followed the Get Started guide to build the Helpdesk app and then followed the Whats next section where we have a link to learn how to use Code interfaces. While I perfectly understood how to use the define_for , because it builds on top of the Helpdesk app, I wasn't able to grasp how to use the define_interface, because the example for it doesn't build on top of the Helpdesk app. Share the problematic documentation define_for and define_interface Notice how we included a specific Api module using define_for above. Without this, no functions will be defined in the resource. This is because you might want to define the interface for multiple resources in a single module. While we encourage the use of define_for Api , it is not the only way to do it. You could also do something like this:

defmodule MyApp.MyApi.Interface do
  require Ash.CodeInterface

  Ash.CodeInterface.define_interface(MyApp.MyApi, MyApp.Resource1)
  Ash.CodeInterface.define_interface(MyApp.MyApi, MyApp.Resource2)
end

defmodule MyApp.MyApi.Interface do
  require Ash.CodeInterface

  Ash.CodeInterface.define_interface(MyApp.MyApi, MyApp.Resource1)
  Ash.CodeInterface.define_interface(MyApp.MyApi, MyApp.Resource2)
end

And then call functions on MyApp.MyApi.Interface instead. How can I use the above code example in the context of the Helpdesk app?

Ash HQ

Guide: Get Started

Read the "Get Started" guide on Ash HQ

Ash HQ

Guide: Code Interface

Read the "Code Interface" guide on Ash HQ

22 Replies

ZachDaniel•3y ago

It should look something like this:

defmodule Helpdesk.Support.Interface do
  Ash.CodeInterface.define_interface(Helpdesk.Support, Helpdesk.Support.Ticket)

…repeat for additional resources
end

defmodule Helpdesk.Support.Interface do
  Ash.CodeInterface.define_interface(Helpdesk.Support, Helpdesk.Support.Ticket)

…repeat for additional resources
end

However, you will likely want to change the names in the code_interface block I.e from :open -> :open_ticket

exadra37OP•3y ago

I tried that approach before, but doesn't work unless I also use the code_interface in the Helpdesk.Support.Ticket module.

ZachDaniel•3y ago

Yeah, that is how it works It defines the functions that are described in the resource

exadra37OP•3y ago

The docs suggest that you use code_interface or instead define_interface

ZachDaniel•3y ago

You can use define_for or define_interface So with

code_interface do
  define :foo
end

code_interface do
  define :foo
end

if I say

code_interface do
  define_for Api
  define :foo
end

code_interface do
  define_for Api
  define :foo
end

then I will get Resource.foo() If, in another module say MyApp.MyApi.Interface, I say

Ash.CodeInterface.define_interface(Api, Resource)

Ash.CodeInterface.define_interface(Api, Resource)

Then I will get MyApp.MyApi.Interface.foo()

exadra37OP•3y ago

Thats confusing and not how the docs suggest

While we encourage the use of define_for Api , it is not the only way to do it. You could also do something like this:

ZachDaniel•3y ago

🤔 You don't have to use define_for Api So I'm not sure what you mean

code_interface do
  define_for Api #<- optional. Make it define functions in the current module
  define :foo # <- you have to do this part no matter what, so we know what functions to define
end

code_interface do
  define_for Api #<- optional. Make it define functions in the current module
  define :foo # <- you have to do this part no matter what, so we know what functions to define
end

exadra37OP•3y ago

exadra37OP•3y ago

Yes I now understand what you say, but the docs relay other perception Reading the docs indicates that you use one or the other, not both

ZachDaniel•3y ago

What change would you suggest?

Notice how we included a specific Api module using define_for above. Without this, no functions will be defined in the resource. This is because you might want to define the interface for multiple resources in a single module. While we encourage the use of define_for Api , it is not the only way to do it.

We are suggesting the define_for is optional and it is

exadra37OP•3y ago

I ma not Englishj native, then it may be because of that that I don't get it's optional

ZachDaniel•3y ago

well, I'm happy for the documentation to be more clear, but its hard for me to see it like a beginner because I already know it so well. So if you'd like to make a PR with suggested changes, I'm happy to review 😄

exadra37OP•3y ago

for me the docs read as if we use one or the other, not both, therefore I would suggest you add the comments from the example above into the docs and be a lit more explicit in the phrasing ok, i can do a PR I also cannot find how to fetch a resource by id the read action returns all resources the Getting started guide should be more complete and have a complete CRUD Helpdesk

ZachDaniel•3y ago

There are very few getting started guides in the wild that explain an entire application from top to bottom But we're working on our documentation still

ZachDaniel•3y ago

for example: https://github.com/ash-project/ash/pull/504

GitHub

getting-started-with-phoenix docs by chrishop · Pull Request #504 ·...

docs: 3rd draft of getting-started-with-ash-and-phoenix Update: 09/02/2023 renamed from getting-started-with-phoenix -> getting-started-with-ash-and-phoenix many minor changes in phrasing, form...

exadra37OP•3y ago

Yes, but the getting started are very improtant to not loose potential users and your current getting started almost made me go away of Ash if it wasn't your propmt feedabck 🙂

ZachDaniel•3y ago

Just takes time 🙂 Realistically, Ash is a huge framework and so there will always be things people need to discover on their own. But more content is in the works (including books).

exadra37OP•3y ago

I know that its a huge endeavor and as a Developer Advocate on my current role I know how important is to have a very easy to follow and complete as possible quickstart to not loose developers, that's why I am reporting to you that you should rethink your current approach to the get started In the DevRel we cal this to give a very first good impression on the developer experience (DX)

ZachDaniel•3y ago

Understood and agreed 🙂 Thats why I pointed out that we are actively working on it 👍

exadra37OP•3y ago

You pointed out Phoenix, not this getting started, that is your current starting point, unless Phoenix will become the starting point the developer journey with ASH?

ZachDaniel•3y ago

Well, we're working on lots of different aspects of it, I mean thats just one example

exadra37OP•3y ago

Gaming

Programming

How to use define_interface example in docs it's not clear

Did you find this page helpful?