How to work with a resource and a httpLabel

[zetashift]

Hiya,

I'm still new to Smithy and smithy4s. I'm trying to learn it by writing small services, one of these is a contacts list, just like a todo list...but with contacts heh.

My current model has a resource : Contact and it uses the id of a Contact in uri's, but this isn't possible because the resource identifier isn't allowed to have @httpLabel.

Am I modeling wrong, or is there a better/more standard way to do these type of things?

I have the following smithy file:

$version: "2"

namespace smithy4s.contacts

use smithy4s.api#simpleRestJson
use smithy4s.api#UUID

@simpleRestJson
service ContactsService {
  version: "0.0.1"
  operations: [AddContact, DeleteContact, ShowContact, ShowContacts]
}

@http(method: "POST", uri: "/contacts/{contactId}", code: 200)
operation AddContact {
  input: AddContactInput
  errors: [InvalidInput]
}

@idempotent
@http(method: "DELETE", uri: "/contacts/{contactId}", code: 200)
operation DeleteContact {
  errors: [InvalidInput]
}

@input
structure AddContactInput for Contact {
  @required
  $contactId
}

@readonly
@http(method: "GET", uri: "/contacts/{contactId}", code: 200)
operation ShowContact {
  output: ShowContactOutput
  errors: [InvalidInput]
}

@readonly
@http(method: "GET", uri: "/contacts", code: 200)
operation ShowContacts {
  output: ShowContactsOutput
}

@output
structure ShowContactsOutput {
  @required
  contacts: Contacts
}

@output
structure ShowContactOutput for Contact {
  @required
  $contactId
  
  name: String
}

resource Contact {
  identifiers: { contactId: ContactId }
}

list Contacts {
  member: ContactId
}

@error("server")
structure InvalidInput {
  @required
  message: String
}

@uuidFormat
string ContactId

[Baccata]

@zetashift, thanks for the interest :)

For starters, let me say that in the current version, Smithy4s doesn't have any bespoke support for Resource whatsoever, so I obviously cannot give you a very informed piece of advice on resources. I've not ever used resources myself, and though we are planning on support it eventually, we haven't even started thinking about the "how" of a possible support.

Now, that being said, let's try to minimise your example to make the problem clearer and identify a solution. This below seems to work. As you can see, I've added the @httpLabel annotation in the definition of AddContactInput

$version: "2"

namespace contacts

use smithy4s.api#simpleRestJson
use smithy4s.api#UUID
use smithy4s.api#uuidFormat


@simpleRestJson
service ContactsService {
  version: "0.0.1"
  operations: [AddContact]
}

@http(method: "POST", uri: "/contacts/{contactId}", code: 200)
operation AddContact {
  input: AddContactInput
}


@input
structure AddContactInput for Contact {
  @httpLabel
  @required
  $contactId
}


resource Contact {
  identifiers: { contactId: ContactId }
}


@uuidFormat
string ContactId

If you're worried about the repetition between various operations, you could use mixins to clear the boilerplate :

@mixin
structure ContextInput for Contact {
  @httpLabel
  @required
  $contactId
}

structure AddContactInput with [ContextInput]{
}

PS please don't start your namespaces with smithy4s, we reserve the right to do weird things when namespaces start with smithy4s.

[zetashift]

It seems I had very wrong assumptions, sorry. I knew the docs mentioned that Resource of type shape are unsupported, but I interpreted like "oh so a certain type of resource is unsupported".
AFAIK I don't have to use a resource, I used resources because all the smithy docs use it, and I'm trying to be more comfortable with the IDL. And the boilerplate was a concern, but praise mixin support in 2!

Also last wrong assumption was that the quickstart code uses the smithy4s namespace(smithy4s.hello) so I thought that namespace was necessary to active some codegen or something D:

One last small question, I think I can safely change to Contact to a structure right(using mixins to reduce the duplication)?

[Baccata]

One last small question, I think I can safely change to Contact to a structure right(using mixins to reduce the duplication)?

I think so, for sure.

[zetashift]

Thank you very much! For the answer and the great library :D

[zetashift]

So I don't know if structure for Contact here is good/acceptable usage. Maybe Contact is better off being a resource?
I don't have any specific requirements.

Currently I have this, after trying to clean up the code a bit(lil bit minified):

@simpleRestJson
service ContactsService {
  version: "0.0.1"
  operations: [AddContact, DeleteContact, ShowContact, ShowContacts]
}

@idempotent
@http(method: "DELETE", uri: "/contacts/{contactId}", code: 200)
operation DeleteContact {
  input: Contact,
  errors: [InvalidInput]
}

@http(method: "POST", uri: "/contacts/{contactId}", code: 200)
operation AddContact {
  input: AddContactInput
  errors: [InvalidInput]
}

@input
structure AddContactInput with [ContactContext] {
  @required
  $contactId
}

@mixin
structure ContactContext {
  @httpLabel
  @required
  contactId: ContactId
}

structure Contact {
  @httpLabel
  @required
  contactId: ContactId
}

@uuidFormat
string ContactId

Is this adequate? The Delete having a Contact as input, versus AddContactInput which uses a mixin, feels kinda funky.

[Baccata]

Here's a corrected spec :

$version: "2"

namespace zetashift.contacts


service ContactsService {
  version: "0.0.1"
  operations: [AddContact, DeleteContact, GetContact],
  errors: [InvalidInput]
}

@http(method: "POST", uri: "/contacts", code: 200)
operation AddContact {
  input := {
    name: String
    description: String
  },
  output := {
    contactId: ContactId
  }
}

@idempotent
@http(method: "DELETE", uri: "/contacts/{contactId}", code: 200)
operation DeleteContact {
  input := with[ContactInput] {},
}

@readonly
@http(method: "GET", uri: "/contacts/{contactId}", code: 200)
operation GetContact {
  input := with[ContactInput]{},
  output: Contact
}

@mixin
structure ContactInput {
  @required
  @httpLabel
  contactId: ContactId
}

string ContactId
structure Contact {
  name: String
  description: String
}

@error("client")
structure InvalidInput {
  @required
  message: String
}

But here I have it in a structure and it still fails

So, the input and output of an operation MUST be structures, and the httpLabel will only be mapped to path parameters when it is applied on a top-level member in that structure.

When you do the following :

@readonly
@http(method: "GET", uri: "/contacts/{contactId}", code: 200)
operation GetContact {
  input := {
   contact: Contact
  }
  ... 

.... what you're modelling is essentially

def getContact(input: GetContactInput) : ...
case class `GetContactInput(contact: Contact)` 
case class `Contact(@httpLabel contactId: ContactId, ...)`

Because the @httpLabel annotation is applied on a nested member, smithy complains. It is simply not reconciling http-bindings in nested data structures with the requirements. So basically what I've done is make ContactInput a mixin (which is basically akin to a Scala trait), and apply that mixin on the inlined input.

I've also made the InvalidInput a client error (ie the kind of error that fall into the 4xx range of http status codes), and moved it to the service definition to reduce the repetition.

[Baccata]

PS : I highly recommend you to install vscode and one of the Smithy extensions for it, either the one from AWS or our own. The two use the same LSP implementation (we implemented the first few iterations and have donated it to AWS, and we might deprecate our extension in the future as a result).

AWS is developing an Intellij plugin, but until it's there, vscode can give you a very nice editor experience for editing smithy files.

[zetashift]

Ah thank you so much!! I didn't know you could put mixins in inline input definition.
I hope I get better at mastering this Smithy IDL x).

So when you have something like:

@http(method: "POST", uri: "/{name}", code: 200)
operation Hello {
  input: Person
  output: Greeting
}

structure Person {
  @httpLabel
  @required
  name: String

Person is seen as a non nested member?

[zetashift]

Ah yea I already use the Smithy extension, the extension + Smithy errors(very nice errors !), helped me avoid having a huge amount of "
how do I do this" moments, and ask you more dumb questions :P.

But since there are so many things you can do with Smithy, and with the new-ness of this library, I am mostly unsure of the "idiomatic" ways to do things, also because I only know a little about everything

[Baccata]

So when you have something like:
Person is seen as a non nested member?

Yup.