design methods for feature service attachments

[COV-GIS]

What do you think about this @jgravois and @tomwayson?

A single attachments() method with operation param for the 6 attachment ops and corresponding interfaces for the request params. Down and dirty example below obviously needs much, but for a conceptual start. Just an idea I had while thinking about possibly tackling attachments.

import { request, IRequestOptions } from "@esri/arcgis-rest-request";

export interface IAddAttachmentParameters extends IRequestOptions {
  /**
   * Attachment file.
   */
    attachment: File;
    // other add attachment params
}

// parameter interfaces for the other attachment operations

export interface IAttachmentsOptions {
  /**
   * Feature service url.
   */
  url: string;
  /**
   * Attachment operation to perform.
   */
  operation: "query" | "get" | "infos" | "add" | "delete" | "update";
  /**
   * Attachment parameters for corresponding operation.
   */
  params: IAddAttachmentParameters; // and othersParams
}

export function attachments(
  options: IAttachmentsOptions
): Promise<any> {
  // need to construct proper url based attachment operation and possibly params for some operations
  const url = `${options.url}/addAttachment`;

  const requestParams = options.params;

  return request(url, requestParams);
}

[jgravois]

i think a terse, multi-operation supporting method could actually work quite well for attachments.

take a look at #214 though. we ended up updating the signatures for feature service methods to steer away from defining custom params and extend IRequestOptions consistently instead.

[tomwayson]

We definitely want to steer away from custom params and do what we've done in #214. Specifically in this case that would mean removing IAddAttachmentParameters and adding attachment?: File to IAttachmentsOptions.

That begs the question though, should all of these operations share a single fn? I took a quick look at the corresponding REST APIs, and it seems to me that:

• infos and get work on a single feature and have similar params (w/ get having the additional attachement id)
• query and delete can work on multiple features and have similar params
• add and update work on a single feature and have similar params

So, I'd say there's 4 interfaces there:

• IAttachmentsOptions - used for info, includes feaureId: number
• IAttachmentOptions - extends IAttachmentsOptions w/ attachmentId: number, used for get operation
• IEditAttachmentOptions - extends IAttachementOptions and is used for add/update operations
• IQueryAttachmentOptinos - used for query/delete operations

And at that point, I'd be inclined to use seperate fns

• attachments(url, IAttachementsOptions)
• attachement(url, IAttachmentOptions)
• queryAttachments(url, IQueryAttachmentOptions)
• addAttachement(url, IEditAttachmentOptions)
• updateAttachement(url, IEditAttachmentOptions)
• deleteAttachments(url, IQueryAttachmentOptions)

That's my 2 centavos.

[COV-GIS]

Thanks for the input. The single method idea came to me b/c I'm currently using a single attachment endpoint and request now for attachments. Perhaps a bit over simplified.

If you're amicable, I'll make a start as time allows, and ding you for thoughts and comments on my branch.

[tomwayson]

That would be awesome @COV-GIS!

To be clear, your input based on real-world use cases is very valuable. So if what I've suggested above (and below), which is based entirely on reflecting the current REST API within the constraints we've come up w/ for fn signatures, doesn't "feel" right to how you want to work w/ attachments, I welcome any suggestions for syntactic sugar.

Also, it looks like I got those constraints wrong (again). We really ought to write those down somewhere. Turns out, the constraint is all fns take a single options parameter, which extends some descendant of IRequestOptions. Also, after thinking about this, I'd prefix attachments and attachment w/ get to make them more consistent with other fn names used throughout arcgis-rest-js. Those changes would mean adding url: string to IAttachementsOptions extending the interfaces below from IFeatureRequestOptions and then these signatures:

• getAttachments(IAttachementsOptions) getAttachments(IFeatureRequestOptions)
• getAttachement(IAttachmentOptions)
• queryAttachments(IQueryAttachmentOptions)
• addAttachement(IEditAttachmentOptions)
• updateAttachement(IEditAttachmentOptions)
• deleteAttachments(IQueryAttachmentOptions)

[tomwayson]

mean adding url: string to IAttachementsOptions

Or better yet, instead of IAttachementsOptions just use the existing IFeatureRequestOptions and have IAttachmentOptions extend that.

[COV-GIS]

In the case of attachments the base url is of the feature-service-feature variety.

1. The url param is the feature url formed by the user.
2. The url param is the feature service url, with a second id param, and the api forms the url.

I prefer the first.

What say you @tomwayson ?

[jgravois]

if i'm understanding correctly, i think it makes sense to mimic getFeature() (and reuse the interface).

[tomwayson]

In the case of attachments the base url is of the feature-service-feature variety.

I think that's true for infos, get, add, and update, but query operates on the whole layer. Also, looks like I was wrong about delete above - it does operate at the feature level. I think that means we need another interface for deleting: deleteAttachments(IDeleteAttachmentOptions)

As @jgravois says, I think the above interfaces should extend the existing IFeatureRequestOptions, which would use your second approach:

The url param is the feature service url, with a second id param, and the api forms the url.

[COV-GIS]

Check roger.

get can simply use IFeatureRequestOptions. While add can extent it. update and delete can extent it too but will require 2 id params for the feature and the attachment. My thinking was fewer params, and looking at it from the feature POV and not the service.

Thanks for the input.